Участие в разработке документации для разработчиков Смешанная реальность

Статья
03/21/2023

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

Документация по Смешанная реальность теперь размещена в Microsoft Learn, в которой используются функции Markdown на основе GitHub с функциями Markdig. Содержимое, которое вы редактируете в этом репозитории, отформатируется в стилизованные страницы, которые отображаются в /windows/mixed-reality.

На этой странице описаны основные шаги и рекомендации по участию в разработке, а также ссылки на основы Markdown. Спасибо за Ваше предложение!

Доступные репозитории

Имя репозитория	URL-адрес
Объектные привязки Azure	MicrosoftDocs/azure-docs/articles/object-anchors
Удаленная отрисовка Azure	MicrosoftDocs/azure-docs/articles/remote-rendering
Пространственные привязки Azure	MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens	MicrosoftDocs/HoloLens
Смешанная реальность	MicrosoftDocs/mixed-reality
Руководство для любителей виртуальной реальности	MicrosoftDocs/mixed-reality/enthusiast-guide

Перед началом работы

Создайте учетную запись GitHub, если не сделали это ранее.

Примечание

Если вы сотрудник корпорации Майкрософт, свяжите свою учетную запись GitHub с псевдонимом Microsoft на портале Microsoft Open Source. Присоединитесь к организациям Microsoft и MicrosoftDocs.

При настройке учетной записи GitHub также рекомендуется предпринять следующие меры безопасности:

Создайте надежный пароль для учетной записи GitHub.
Включите двухфакторную проверку подлинности.
Сохраните коды восстановления в надежном месте.
Обновите параметры общего профиля.
- Укажите свое имя, а также задайте для параметра Public email (Общий адрес электронной почты) значение Don't show my email address (Не показывать мой адрес электронной почты).
- Мы рекомендуем добавить изображение профиля, так как на страницах документации, которую вы помогаете разрабатывать, будет отображатся эскиз.
Если вы планируете использовать командную строку, рассмотрите возможность настройки диспетчера учетных данных Git для Windows. Используя этот инструмент, вам не придется вводить пароль каждый раз, когда работаете с документацией.

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

Изменение существующей статьи

Используйте следующий рабочий процесс, чтобы изменить существующую статью с помощью GitHub в веб-браузере:

Перейдите к статье, которую вы хотите изменить, в папке mixed-reality-docs.
Нажмите кнопку редактирования (значок карандаша) в правом верхнем углу, чтобы автоматически создать вилку одноразовой ветви от главной ветви.
Измените содержимое статьи в соответствии с основами Markdown.
Обновите метаданные в верхней части каждой статьи:
- title: заголовок страницы, который отображается на вкладке браузер при просмотре статьи. Заголовки страниц используются для SEO и индексации, поэтому не меняйте заголовок, если в этом нет необходимости (хотя это менее критично до публикации документации).
- description: введите краткое описание содержимого статьи, которое увеличивает SEO и улучшает обнаружение.
- author: если вы являетесь основным владельцем страницы, добавьте здесь псевдоним GitHub.
- ms.author: если вы являетесь основным владельцем страницы, добавьте сюда псевдоним Майкрософт (вам не нужен @microsoft.comтолько псевдоним).
- ms.date: обновляйте дату, только если добавляете на страницу важное содержимое, а не вносите исправления, например вносите уточнения, изменяете форматирование, проверяете грамматику или орфографию.
- keywords: ключевые слова в SEO (оптимизация поисковой системы). Добавьте связанные с вашей статьей ключевые слова, разделив их запятыми и пробелами, но не указывая знак препинания после последнего ключевого слова в списке. Добавлять глобальные ключевые слова, применимые ко всем статьям, не нужно, так как их нужно указывать в другом месте.
Когда вы завершите изменение статьи, прокрутите страницу вниз и выберите Propose file change (Предложить изменение файла).
На следующей странице выберите Создать запрос на вытягивание , чтобы объединить автоматически созданную ветвь с master.
Повторите описанные выше действия для следующей статьи, которую необходимо изменить.

Переименование или удаление существующей статьи

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

Чтобы добавить перенаправление в файл .openpublishing.redirection.json, добавьте запись в массив redirections:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

source_path — это относительный путь к репозиторию старой статьи, которую вы удаляете. Убедитесь, что путь начинается с mixed-reality-docs и заканчивается на .md.
redirect_url — это относительный общедоступный URL-адрес от старой статьи к новой. Убедитесь, что этот URL-адрес не содержит mixed-reality-docs или .md, так как он ссылается на общедоступный URL-адрес, а не путь к репозиторию. Также допускается связывание с разделом в новой статье с помощью #section. Кроме того, при необходимости вы можете использовать здесь абсолютный путь к другому сайту.
redirect_document_id указывает, следует ли сохранить идентификатор документа из предыдущего файла. Значение по умолчанию — false. Используйте true, если вам нужно сохранить значение атрибута ms.documentid из перенаправленной статьи. Если вы решили сохранить идентификатор документа, такие данные, как просмотры страниц и рейтинги, будут сохранены на целевой статье. Этот вариант в первую очередь предназначен для перенаправления при переименовании, а не создании указателя на другую статью, содержащую только часть того же контента.

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

Создание статьи

Используйте следующий рабочий процесс для создания статей в репозитории документации, открыв GitHub в веб-браузере:

Создайте вилку от ветви "master" MicrosoftDocs/mixed-reality (с помощью кнопки Fork в правом верхнем углу).
В папке mixed-reality-docs выберите Создать файл в правом верхнем углу.
Создайте имя страницы для статьи (используйте дефисы вместо пробелов и не используйте знаки препинания или апострофы), добавив .md.

Важно!

Убедитесь, что вы создали новую статью в папке mixed-reality-docs. Это можно подтвердить, проверив значение "/mixed-reality-docs/" в строке нового имени файла.
В верхней части новой страницы добавьте следующий блок метаданных:
```
---
title:
description:
author:
ms.author:
ms.date:
ms.topic: article
keywords:
---
```
Заполните соответствующие поля метаданных в соответствии с инструкциями в разделе выше.
Напишите содержимое статьи, используя основы Markdown.
Добавьте раздел ## See also в нижнюю часть статьи, указав ссылки на другие важные статьи.
По завершении выберите Commit new file (Подтвердить новый файл).
Выберите Создать запрос на вытягивание и объедините ветвь master вилки в MicrosoftDocs/mixed-reality 'master' (убедитесь, что стрелка указывает правильный путь).

Базовые сведения о Markdown

С помощью следующих ресурсов вы узнаете, как редактировать документацию с помощью языка Markdown:

Добавление таблиц

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

Кроме того, если вы используете при изменении документации Visual Studio Code (см. ниже), используйте расширение для создания документации с помощью Markdown для Visual Studio Code, которое также упрощает создание таблиц.

Добавление изображений

Вам потребуется отправить изображения в папку mixed-reality-docs/images в репозитории, а затем сослаться на них соответствующим образом в статье. Изображения будут автоматически отображаться в полноразмерном виде, то есть большие изображения будут полностью заполнять статью по ширине. Мы рекомендуем изменить размер изображений, прежде чем добавлять их. Рекомендуемая ширина составляет от 600 до 700 пикселей, однако иногда вам понадобится увеличить или уменьшить размер, если это снимок экрана с трудными для понимания сведениями или часть такого снимка экрана.

Важно!

Добавлять изображения в разветвленный репозиторий можно только перед слиянием. Поэтому, если вы планируете добавлять изображения в статью, используйте Visual Studio Code, чтобы сначала добавить изображения в папку images вилки или убедиться, что вы сделали следующее в веб-браузере:

Вилку репозитория MicrosoftDocs/смешанной реальности.
Изменили статью в вилке.
Загружены изображения, на которые вы ссылаетесь в статье, в папку mixed-reality-docs/images в вилке.
Создан запрос на вытягивание для объединения вилки в ветвь "master" MicrosoftDocs/mixed-reality.

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

Предварительный просмотр статьи

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

Примечание

Предварительный просмотр промежуточных изменений доступен только сотрудникам Корпорации Майкрософт

Сотрудники Майкрософт: после объединения ваших вкладов в ветвь main вы можете просмотреть содержимое, прежде чем оно становится общедоступным, по адресу /windows/mixed-reality?branch=main. Найдите статью, используя оглавление в левом столбце.

Редактирование в браузере и редактирование с помощью настольного клиента

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

Отсутствие проверки орфографии.
Вы не получаете смарт-ссылок на другие статьи (необходимо вручную ввести имя файла статьи).
Загрузка изображений и создание ссылок на них могут доставить немало хлопот.

Если вы не хотите разбираться с этими проблемами, используйте при работе над проектом настольный клиент, например Visual Studio Code с парой полезных расширений.

Использование Visual Studio Code

В связи с указанными выше причинами, вы можете предпочесть для редактирования документации настольный клиент, а не веб-браузер. Рекомендуется использовать Visual Studio Code.

Настройка

Выполните указанные далее действия, чтобы настроить Visual Studio Code для работы с этим репозиторием:

В веб-браузере:
1. Установите Git для своего компьютера.
2. Установите Visual Studio Code.
3. Создайте вилку MicrosoftDocs или смешанной реальности , если вы еще этого не сделали.
4. В вилке выберите Clone or download (Клонировать или скачать) и скопируйте URL-адрес.
Создайте локальный клон вилки в Visual Studio Code:
1. В меню Вид выберите Палитра команд.
2. Введите команду Git:Clone.
3. Вставьте скопированный URL-адрес.
4. Выберите место на компьютере, куда нужно сохранить клон.
5. Выберите Open repo (Открыть репозиторий) во всплывающем окне.

Редактирование документации

Используйте следующий рабочий процесс для внесения изменений в документацию с помощью Visual Studio Code:

Примечание

Все приведенные выше рекомендации по редактированию и созданию статей, а также основы редактирования Markdown, применимы и при использовании Visual Studio Code.

Убедитесь, что клонированная вилка соответствует официальному репозиторию.
1. В веб-браузере создайте запрос на вытягивание, чтобы синхронизировать последние изменения, внесенные другими участниками в microsoftDocs/mixed-reality master, с вилкой (убедитесь, что стрелка указывает правильный путь).
2. В Visual Studio Code выберите кнопку синхронизации, чтобы синхронизировать недавно обновленную вилку с локальным клоном.
Создавайте или изменяйте статьи в клонированном репозитории с помощью Visual Studio Code.
1. Измените одну или несколько статей (при необходимости добавьте изображения в папку images).
2. Сохраните изменения в обозревателе.
3. Подтвердите все изменения в системе управления версиями (при появлении запроса следует создать сообщение о подтверждении).
4. Нажмите кнопку синхронизации, чтобы синхронизировать изменения с источником (вилка на GitHub).
В веб-браузере создайте запрос на вытягивание, чтобы синхронизировать новые изменения в вилке с MicrosoftDocs/mixed-reality 'master' (убедитесь, что стрелка указывает правильный путь).

Полезные расширения

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

Расширение для создания документации с помощью Markdown для Visual Studio Code. Используйте сочетание клавиш Alt+M, чтобы открыть меню параметров для создания документации, например:
- Поиск отправленных изображений и создание ссылки на них.
- Добавление форматирования, например списков, таблиц и связанных с документацией вызовов, таких как >[!NOTE].
- Поиск внутренних ссылок и закладок (ссылки на определенные разделы на странице), а также создание ссылок на них.
- Выделение ошибок форматирования (при наведении указателя мыши на ошибку будут отображатся дополнительные сведения).
Средство проверки орфографии кода. Средство будет подчеркивать слова с ошибками. Щелкните правой кнопкой мыши слово с ошибками, чтобы изменить его или сохранить в словаре.

Участие в разработке документации для разработчиков Смешанная реальность

Доступные репозитории

Перед началом работы

Изменение существующей статьи

Переименование или удаление существующей статьи

Создание статьи

Базовые сведения о Markdown

Добавление таблиц

Добавление изображений

Предварительный просмотр статьи

Редактирование в браузере и редактирование с помощью настольного клиента

Использование Visual Studio Code

Настройка

Редактирование документации

Полезные расширения

Дополнительные ресурсы