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

MRTK

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

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


Функциональные возможности и разметка

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

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

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

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

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

Тодос

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

Если добавить 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. Не используйте "небрежные фразы".
  6. Избегайте звучать чрезмерно взволнован, мы не должны продавать ничего.
  7. Аналогичным образом, избегайте чрезмерно драматических. Восклицательные знаки редко требуются.

Регистр букв

  • Используйте вариант предложения для заголовков. Ie. прописные буквы и имена, но ничего другого.
  • Используйте обычный английский язык для всего остального. Это означает, что не прописываются произвольные слова, даже если они содержат специальное значение в этом контексте. Предпочитайте курсивный текст для выделения определенных слов, см. ниже.
  • Если ссылка внедрена в предложение (который является предпочтительным методом), стандартное имя главы всегда использует прописные буквы, тем самым нарушая правило произвольной прописной буквы внутри текста. Поэтому используйте настраиваемое имя ссылки для исправления прописной буквы. Например, ниже приведена ссылка на документацию по элементу управления bounds .
  • Выполните прописные имена, такие как 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, чтобы открыть меню параметров разработки документов.

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

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

См. также раздел