Поделиться через

Рекомендации по документации — MRTK2

  • Статья
MRTK

В этом документе описаны рекомендации и стандарты документации по набору средств Смешанная реальность (MRTK). Это содержит общие сведения о технических аспектах написания и создания документации, для выделения распространенных ошибок и описания рекомендуемого стиля написания.

Сама страница должна служить примером, поэтому она использует предполагаемый стиль и наиболее распространенные функции разметки документации.

Функции и разметка

В этом разделе описываются часто необходимые функции. Чтобы узнать, как они работают, просмотрите исходный код страницы.

  1. Нумерованные списки
    1. Вложенные нумерованные списки с по крайней мере 3 пустыми пробелами
    2. Фактическое число в коде не имеет значения; Синтаксический анализ будет заботиться о настройке правильного номера элемента.
  • Списки точек маркеров
    • Вложенные списки точек маркеров
  • Текст полужирным шрифтом **double asterisk**
  • курсивный текст с _подчеркиванием_ или *одним звездочкой*
  • Текст highlighted as code в предложении "using backquotes"
  • Ссылки на страницы документации MRTK
  • Ссылки на привязки на странице; привязки формируются путем замены пробелов дефисом и преобразования в нижний регистр

Для примеров кода мы используем блоки с тремя обратными знаками '' и укажите csharp в качестве языка для выделения синтаксиса:

int SampleFunction(int i)
{
   return i + 42;
}

При упоминании кода в предложении use a single backtick.

ToDOs

Избегайте использования TODOs в документах, так как с течением времени эти TODOs (например, код TODOs) обычно накапливаются и сведения о том, как их следует обновлять и почему теряется.

Если необходимо добавить TODO, выполните следующие действия.

  1. Отправьте новую проблему на Github, описывающую контекст toDO, и укажите достаточно фона, чтобы другой участник мог понять, а затем обратиться к TODO.
  2. Ссылка на URL-адрес проблемы в todo в документации.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Краткое размытие по вопросу ->

Выделенные разделы

Чтобы выделить определенные точки для читателя, используйте > [! ПРИМЕЧАНИЕ] , > [! ПРЕДУПРЕЖДЕНИЕ] и > [! ВАЖНО] для создания следующих стилей. Рекомендуется использовать заметки для общих точек и предупреждений и важных точек только для особых случаев.

Примечание.

Пример заметки

Предупреждение

Пример предупреждения

Внимание

Пример важного комментария

Макет страницы

Введение

Часть сразу после основного заголовка главы должна служить кратким введением в то, что о главе. Не делайте это слишком длинным, вместо этого добавляйте вложенные заголовки. Они позволяют ссылаться на разделы и сохраняться в виде закладок.

Основной текст

Используйте заголовки двухуровневого и трехуровневого уровня, чтобы структурировать остальные.

Мини-разделы

Используйте полужирную строку текста для блоков, которые должны выделиться. Мы можем заменить это четырьмя заголовками в какой-то момент.

Раздел "См. также"

Большинство страниц должны заканчиваться главой с именем See также. Эта глава — это просто список ссылок на страницы, связанные с этой темой. Эти ссылки также могут отображаться в тексте страницы, если это необходимо, но это не обязательно. Аналогичным образом текст страницы может содержать ссылки на страницы, которые не связаны с основным разделом, они не должны быть включены в список "См. также ". См . раздел "См. также" в качестве примера для выбора ссылок.

Оглавление (TOC)

Файлы toc используются для создания полос навигации в документации по MRTK github.io. При добавлении нового файла документации убедитесь, что в одном из toc.yml файлов папки документации есть запись. В навигации документации разработчика отображаются только статьи, перечисленные в файлах toc. В папке документации может быть файл toc для каждой вложенной папки, которая может быть связана с любым существующим файлом toc, чтобы добавить его в виде подраздела в соответствующую часть навигации.

Стиль

Создание стиля

Общее правило отпечатка: попробуйте прозвучить профессиональным. Это обычно означает, чтобы избежать "разговорного тона". Кроме того, старайтесь избежать гипербола и сенсации.

  1. Не пытайтесь быть (чрезмерно) смешно.
  2. Никогда не писать "Я"
  3. Избегайте "мы". Обычно это можно легко перефразировать, используя MRTK. Пример: "мы поддерживаем эту функцию" —> "MRTK поддерживает эту функцию" или "поддерживаются следующие функции..."
  4. Аналогичным образом старайтесь избежать "вы". Пример: "С помощью этого простого изменения шейдер становится настраиваемым!" -> "Шейдеры можно настроить с небольшими усилиями".
  5. Не используйте фразы sloppy.
  6. Избегайте чрезмерного волнения, мы не должны продавать ничего.
  7. Аналогичным образом избегайте чрезмерно драматичного. Восклицательные знаки редко требуются.

Регистр букв

  • Используйте вариант предложения для заголовков. Т. е. заглавная буква и имена, но ничего другого.
  • Используйте обычный английский для всего остального. Это означает, что не прописывают произвольные слова, даже если они имеют особое значение в этом контексте. Предпочитайте курсивный текст для выделения определенных слов, см. ниже.
  • Если ссылка внедрена в предложение (который является предпочтительным методом), стандартное имя главы всегда использует заглавные буквы, поэтому нарушает правило произвольной прописной буквы внутри текста. Поэтому используйте пользовательское имя ссылки для исправления заглавной буквы. Например, ниже приведена ссылка на документацию по элементу управления границ.
  • Выполните прописные имена, такие как Unity.
  • При написании редактора Unity не прописывать заглавную букву.

Выделение и выделение

Существует два способа подчеркнуть или выделить слова, сделать их смелыми или сделать их курсивными. Эффект полужирного текста заключается в том, что полужирный текст вылипает и поэтому можно легко заметить при перемечении фрагмента текста или даже просто прокручивать страницу. Смелый отличный, чтобы выделить фразы, которые люди должны помнить. Однако редко используйте полужирный текст, так как он обычно отвлекает.

Часто один хочет либо "группировать" то, что принадлежит логически вместе или выделить конкретный термин, потому что он имеет особое значение. Такие вещи не должны выделяться из общего текста. Используйте курсивный текст в качестве упрощенного метода , чтобы выделить что-то.

Аналогичным образом, если имя файла, путь или запись меню упоминается в тексте, предпочитайте сделать его курсив логически группировать, не отвлекаясь.

Как правило, старайтесь избежать ненужного выделения текста. Специальные термины можно выделить один раз, чтобы читатель знал, не повторять такое выделение на протяжении всего текста, когда он больше не служит ни для каких целей, и только отвлекает.

Упоминание записей меню

При упоминании записи меню, которую пользователь должен щелкнуть, текущее соглашение: Project > Files > Create > Leaf

Вставьте как можно больше полезных ссылок на другие страницы, но каждая ссылка только один раз. Предположим, что читатель щелкает каждую ссылку на странице и думает о том, как это раздражает, если одна и та же страница открывается 20 раз.

Предпочитайте ссылки, внедренные в предложение:

Избегайте внешних ссылок, они могут стать устаревшими или содержать содержимое, защищенное авторским правом.

При добавлении ссылки следует учитывать, следует ли также указывать в разделе "См. также ". Аналогичным образом проверьте, следует ли добавить ссылку на новую страницу.

Изображения и снимки экрана

Используйте снимки экрана с разреженным образом. Обслуживание изображений в документации много работы, небольшие изменения пользовательского интерфейса могут сделать много снимков экрана устаревшими. Следующие правила сокращают усилия по обслуживанию:

  1. Не используйте снимки экрана для вещей, которые можно описать в тексте. Особенно, никогда не снимок экрана сетки свойств для единственной цели отображения имен и значений свойств.
  2. Не добавляйте вещи на снимке экрана, которые не соответствуют показанию. Например, при отображении эффекта отрисовки сделайте снимок экрана окна просмотра, но исключите любой пользовательский интерфейс вокруг него. Показывая некоторый пользовательский интерфейс, попробуйте переместить окна вокруг, чтобы только важная часть была в изображении.
  3. При включении пользовательского интерфейса снимка экрана отображаются только важные части. Например, при разговоре о кнопках на панели инструментов сделайте небольшое изображение, отображающее важные кнопки панели инструментов, но исключите все вокруг него.
  4. Используйте только изображения, которые легко воспроизвести. Это означает, что не красит маркеры или выделения на снимках экрана. Во-первых, нет согласованных правил, как они должны выглядеть, в любом случае. Во-вторых, воспроизведение такого снимка экрана является дополнительным усилием. Вместо этого опишите важные части текста. Существуют исключения для этого правила, но они редки.
  5. Очевидно, что это гораздо больше усилий для воссоздания анимированного GIF-файла. Ожидается, что он должен быть ответственным, чтобы воссоздать его до конца времени, или ожидать, что люди выбросить его, если они не хотят тратить это время.
  6. Держите количество изображений в статье низким. Часто хороший метод — сделать один общий снимок экрана некоторых инструментов, который показывает все, а затем описать остальные в тексте. Это позволяет легко заменить снимок экрана при необходимости.

Некоторые другие аспекты:

  • Пользовательский интерфейс редактора для снимка экрана должен использовать редактор светло-серой темы, так как у всех пользователей есть доступ к темной теме, и мы хотели бы сохранить вещи максимально согласованными.
  • Ширина изображения по умолчанию составляет 500 пикселей, так как это хорошо отображается на большинстве мониторов. Старайтесь не отклонять слишком много от него. Ширина 800 пикселей должна быть максимальной.
  • Используйте PNG для снимков экрана пользовательского интерфейса.
  • Используйте PNG или JPG для трехмерных снимков экрана представления. Предпочесть качество для сжатия.

Список свойств компонента

При документе списка свойств используйте полужирный текст для выделения имени свойства, а затем разрывы строк и обычный текст для их описания. Не используйте вложенные главы или списки точек маркеров.

Кроме того, не забудьте завершить все предложения с периодом.

Контрольный список завершения страницы

  1. Убедитесь, что были выполнены рекомендации этого документа.
  2. Просмотрите структуру документов и проверьте, можно ли упомянуть новый документ в разделе "См. также раздел других страниц".
  3. Если он доступен, у кого-то есть знания о теме, ознакомьтесь со страницей для технической правильности.
  4. У кого-то есть правописание страницы для стиля и форматирования. Это может быть кто-то незнаком с темой, что также рекомендуется получить отзывы о том, насколько понятна документация.

Исходная документация

Документация по API будет создана автоматически из исходных файлов MRTK. Чтобы упростить эту задачу, исходные файлы должны содержать следующие компоненты:

В дополнение к приведенному выше коду следует хорошо комментировать, чтобы обеспечить обслуживание, исправления ошибок и простоту настройки.

Класс, структуру, сводные блоки перечисления

Если класс добавляется в MRTK, его назначение должно быть описано. Это необходимо сделать с помощью сводного блока над классом.

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Если существуют зависимости уровня класса, они должны быть задокументированы в блоке примечаний, непосредственно под сводкой.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Запросы на вытягивание, отправленные без сводок для классов, структур или перечислений, не будут утверждены.

Свойства, метод, сводные блоки событий

Свойства, методы и события (PMEs), а также поля должны быть задокументированы с помощью сводных блоков, независимо от видимости кода (общедоступной, частной, защищенной и внутренней). Средство создания документации отвечает за фильтрацию и публикацию только общедоступных и защищенных функций.

ПРИМЕЧАНИЕ. Сводный блок не требуется для методов Unity (например, Awake, Start, Update).

Документация PME требуется для утверждения запроса на вытягивание.

В рамках сводного блока PME требуется значение и назначение параметров и возвращенных данных.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Общие сведения о версиях и зависимостях компонентов

В сводной документации по API сведения о версии MRTK, в которой была представлена функция, и все зависимости должны быть описаны в блоке примечаний.

Зависимости должны включать расширения и (или) зависимости платформы.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Сериализованные поля

Рекомендуется использовать атрибут подсказки Unity для предоставления документации по среде выполнения для полей скрипта в инспекторе.

Поэтому параметры конфигурации включены в документацию по API, скрипты должны включать по крайней мере содержимое подсказки в сводный блок.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Значения перечисления

При определении и перечислении код также должен документировать значение значений перечисления с помощью сводного блока. При необходимости блоки примечаний можно использовать для предоставления дополнительных сведений для улучшения понимания.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Практические руководства

Многие пользователи Смешанная реальность Toolkit могут не использовать документацию по API. Эти пользователи смогут воспользоваться нашими предварительно созданными, повторно используемыми префабами и скриптами для создания возможностей.

Каждая область функций будет содержать один или несколько файлов markdown (MD), описывающих на достаточно высоком уровне, что предоставляется. В зависимости от размера и (или) сложности данной области функций может потребоваться дополнительное количество файлов до одного указанного компонента.

При добавлении компонента (или изменении использования) необходимо предоставить обзорную документацию.

В рамках этой документации разделы, включая иллюстрации, должны быть предоставлены для предоставления клиентам новых возможностей или концепции при начале работы.

Документация по проектированию

Смешанная реальность предоставляет возможность создавать совершенно новые миры. Часть этого, скорее всего, будет включать создание пользовательских ресурсов для использования с MRTK. Чтобы сделать это как можно более свободно для клиентов, компоненты должны предоставить документацию по проектированию, описывающую любое форматирование или другие требования к ресурсам искусства.

Некоторые примеры, в которых может быть полезна документация по проектированию:

  • Модели курсоров
  • Визуализации пространственного сопоставления
  • Файлы звуковых эффектов

Этот тип документации настоятельно рекомендуется и может быть запрошен в рамках проверка запроса на вытягивание.

Это может отличаться от рекомендаций по проектированию на сайте разработчика MS

Заметки о производительности

Некоторые важные функции стоят на производительности. Часто этот код очень зависит от того, как они настроены.

Например:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Заметки о производительности рекомендуются для тяжелых компонентов ЦП и (или) GPU и могут быть запрошены в рамках проверка запроса на вытягивание. Все применимые заметки о производительности должны быть включены в документацию по API и обзору.

Критические изменения

Документация по критическим изменениям состоит из файла верхнего уровня, который связывается с отдельными breaking-changes.md каждой области компонентов.

Область функций, breaking-changes.md файлов, содержит список всех известных критических изменений для данного выпуска , а также историю критических изменений из прошлых выпусков.

Например:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Сведения, содержащиеся на уровне компонентов, breaking-changes.md файлы будут агрегированы в заметки о выпуске для каждого нового выпуска MRTK.

Любые критические изменения, которые являются частью изменения , должны быть задокументированы в рамках запроса на вытягивание.

Средства редактирования MarkDown

Visual Studio Code — это отличное средство для редактирования файлов markdown, которые являются частью документации MRTK.

При написании документации также рекомендуется установить следующие два расширения:

  • Расширение Markdown для Visual Studio Code — используйте ALT+M, чтобы открыть меню параметров разработки документов.

  • Средство проверки орфографии кода. Средство будет подчеркивать слова с ошибками. Щелкните правой кнопкой мыши слово с ошибками, чтобы изменить его или сохранить в словаре.

Оба из них упаковываются в опубликованный корпорацией Майкрософт пакет разработки документов.

См. также