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

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

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

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

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

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

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

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

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

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

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

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

1. Перейдите к статье, которую вы хотите изменить в папке mixed-reality-docs.

2. Нажмите кнопку редактирования (значок карандаша) в правом верхнем углу, которая автоматически закватит удаленную ветвь от ветви master.

   

3. Измените содержимое статьи в соответствии с основами Markdown.

4. Обновите метаданные в верхней части каждой статьи:

   • title: заголовок страницы, который отображается на вкладке браузер при просмотре статьи. Заголовки страниц используются для SEO и индексации, поэтому не меняйте заголовок, если в этом нет необходимости (хотя это менее критично до публикации документации).
   • description: введите краткое описание содержимого статьи, которое увеличивает SEO и улучшает обнаружение.
   • author: если вы являетесь основным владельцем страницы, добавьте здесь псевдоним GitHub.
   • ms.author: если вы являетесь основным владельцем страницы, добавьте псевдоним Майкрософт здесь (вам не нужно @microsoft.com, просто псевдоним).
   • ms.date: обновляйте дату, только если добавляете на страницу важное содержимое, а не вносите исправления, например вносите уточнения, изменяете форматирование, проверяете грамматику или орфографию.
   • keywords: ключевые слова в SEO (оптимизация поисковой системы). Добавьте связанные с вашей статьей ключевые слова, разделив их запятыми и пробелами, но не указывая знак препинания после последнего ключевого слова в списке. Добавлять глобальные ключевые слова, применимые ко всем статьям, не нужно, так как их нужно указывать в другом месте.

5. Когда вы завершите изменение статьи, прокрутите страницу вниз и выберите Propose file change (Предложить изменение файла).

6. На следующей странице выберите "Создать запрос на вытягивание", чтобы объединить автоматически созданную ветвь в "master".

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

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

Если изменение приведет к переименованию или удалению существующей статьи, обязательно добавьте перенаправление. Таким образом, любой, кто захочет перейти по ссылке на существующую статью, все равно перейдет на нее. Перенаправлениями можно управлять с помощью файла .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 в веб-браузере:

1. Создайте вилку от ветви MicrosoftDocs/mixed-reality master (с помощью кнопки "Вилка " в правом верхнем углу).

   

2. В папке "Mixed-reality-docs" выберите "Создать файл " в правом верхнем углу.

3. Создайте имя страницы для статьи (используйте дефисы вместо пробелов и не используйте знаки препинания или апострофы), добавив .md.

   

   Внимание

   Создайте новую статью из папки "Mixed-reality-docs". Это можно подтвердить, проверив "/mixed-reality-docs/" в новой строке имени файла.

4. В верхней части новой страницы добавьте следующий блок метаданных:

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. Заполните соответствующие поля метаданных в соответствии с инструкциями в приведенном выше разделе.

6. Написание содержимого статьи с помощью основных принципов Markdown.

7. Добавьте раздел ## See also в нижнюю часть статьи, указав ссылки на другие важные статьи.

8. По завершении выберите Commit new file (Подтвердить новый файл).

9. Выберите новый запрос на вытягивание и объедините ветвь "master" в MicrosoftDocs/mixed-reality "master" (убедитесь, что стрелка указывает правильный способ).

   

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

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

• Основы Markdown
• Справочный плакат Markdown на первый взгляд
• Дополнительные ресурсы для написания Markdown для Microsoft Learn

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройка

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

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

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

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

1. Убедитесь, что клонированная вилка соответствует официальному репозиторию.

   1. В веб-браузере создайте запрос на вытягивание, чтобы синхронизировать последние изменения от других участников в MicrosoftDocs/mixed-reality "master" с вилкой (убедитесь, что стрелка указывает правильный путь).

      

   2. В Visual Studio Code выберите кнопку синхронизации, чтобы синхронизировать недавно обновленную вилку с локальным клоном.

      

2. Создавайте или изменяйте статьи в клонированном репозитории с помощью Visual Studio Code.

   1. Измените одну или несколько статей (при необходимости добавьте изображения в папку images).

   2. Сохраните изменения в обозревателе.

      

   3. Подтвердите все изменения в системе управления версиями (при появлении запроса следует создать сообщение о подтверждении).

      

   4. Нажмите кнопку синхронизации, чтобы синхронизировать изменения с источником (вилка на GitHub).

      

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

   

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

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

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