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

В этом документе описаны рекомендации и стандарты документации по набору средств Смешанная реальность (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, и предоставьте достаточно фона, чтобы другой участник мог бы понять, а затем решить проблему.
2. Укажите URL-адрес проблемы в списке дел в документации.

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

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

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

Примечание

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

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

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

Важно!

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

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

Введение

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

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

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

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

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

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

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

Оглавление

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

Стиль

Стиль письма

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

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

Регистр букв

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

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

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

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

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

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

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

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

Ссылки

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

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

• BAD: рекомендации полезны. Дополнительные сведения см. в этой главе .
• ХОРОШО. Рекомендации полезны.

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

• Пример ссылки "см. также" для документации