Прочитать на английском

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


Участие в документации HoloLens

Добро пожаловать в документацию HoloLens! Все статьи, которые вы создаете или редактируете в этом репозитории, будут видимы для общественности.

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

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

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

Имя репозитория URL-адрес
HoloLens MicrosoftDocs/HoloLens
Смешанная реальность MicrosoftDocs/mixed-reality
Руководство по энтузиастам ВИРТУАЛЬНОЙ реальности MicrosoftDocs/mixed-reality/enthusiast-guide

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

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

Примечание

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

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

  • Создайте надежный пароль для учетной записи GitHub.
  • Включите двухфакторную проверку подлинности.
  • Сохраните коды восстановления в безопасном месте.
  • Обновите параметры общедоступного профиля .
    • Задайте имя и попробуйте задать общедоступной электронной почты, чтобы не отображать адрес электронной почты.
    • Мы рекомендуем отправить изображение профиля, так как эскиз показан в статьях Microsoft Learn, которые вы вносите.
  • Если вы планируете использовать командную строку, попробуйте настроить диспетчер учетных данных Git для Windows. Таким образом, вам не придется вводить пароль каждый раз, когда вы вносите вклад.

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

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

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

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

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

    Изменить статью.

    Это автоматически закватит удаленную ветвь по умолчанию, основной.

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

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

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

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

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

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

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

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

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_path — это относительный путь репозитория к старой статье, которую вы удаляете. Убедитесь, что путь начинается с набора документов (в данном случае hololens) и включает расширение файла .md.

  • redirect_url является относительным общедоступным URL-адресом из старой статьи в новую статью. Убедитесь, что этот URL-адрес не содержит .md и начинается с /, так как он ссылается на общедоступный URL-адрес, а не путь к репозиторию. Связывание с разделом в новой статье с помощью #section разрешено. При необходимости можно также использовать абсолютный путь к другому сайту.

  • redirect_document_id указывает, хотите ли сохранить идентификатор документа из предыдущего файла. Значение по умолчанию — false. Используйте true, если вы хотите сохранить значение атрибута ms.documentid из перенаправленной статьи. Если вы сохраните идентификатор документа, данные, такие как представления страниц и ранжирование, будут переданы в целевую статью. Это делается, если перенаправление является главным образом переименованием, а не указателем на другую статью, которая охватывает только одно и то же содержимое.

Если вы добавите перенаправление, удалите старый файл.

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

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

  1. Создайте вилку по умолчанию основнойMicrosoftDocs/hololens с помощью кнопки Fork в правом верхнем углу.

    ветвь по умолчанию с именем main.

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

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

    Назовите новую страницу.

    Важно!

    Создайте новую статью из папки Hololens. Это можно подтвердить, проверив "/hololens/" в новой строке имени файла.

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

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. Заполните соответствующие поля метаданных, как описано ранее в редактировании существующей статьи.

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

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

  8. По завершении выберите Зафиксировать новый файл.

  9. Выберите Новый запрос на вытягивание и объедините ветвь основной в MicrosoftDocs/hololens main (убедитесь, что стрелка указывает на правильное назначение).

    Создать запрос на вытягивание из вилки в MicrosoftDocs/hololens.

Основы Markdown

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

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

Из-за того, как таблицы стилизованы в Microsoft Learn, они не будут иметь границы или настраиваемые стили, даже если вы пытаетесь использовать встроенный CSS. Кажется, что она будет работать в течение короткого периода времени, но в конечном итоге платформа будет отрезать стили из таблицы. Таким образом, спланируйте и оставьте таблицы простыми. Вот сайт, который упрощает таблицы Markdown: [Генератор таблиц]](https://www.tablesgenerator.com/markdown_tables).

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

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

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

Важно!

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

  1. Вилку репозитория MicrosoftDocs/hololens.
  2. Редактировал статью в вилке.
  3. Отправлены изображения, на которые вы ссылаетесь в статье, в папку hololens/images в вилке.
  4. Создайте запрос на вытягивание для объединения вилки в ветвь MicrosoftDocs/hololens main.

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

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

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

Примечание

Предварительный просмотр изменений в Microsoft Learn доступен только сотрудникам Майкрософт.

Сотрудники Майкрософт: когда ваши вклады были объединены в ветвь по умолчанию, основной, вы можете просмотреть содержимое, прежде чем он будет общедоступным в </hololens?branch=main>. Найдите статью с помощью оглавление в левом столбце.

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

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

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

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

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

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

Настройка

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

  1. В веб-браузере:
    1. Установите Git длякомпьютера.
    2. Установите Visual Studio Code.
    3. Fork MicrosoftDocs/hololens, если вы еще не сделали этого.
    4. В вилке выберите Клонировать или скачать и скопируйте URL-адрес.
  2. Создайте локальный клон вилки в Visual Studio Code:
    1. В меню представления выберите палитру команд.
    2. Введите "Git: Клон".
    3. Вставьте скопированный URL-адрес.
    4. Выберите место сохранения клона на компьютере.
    5. Выберите Открыть репозиторий во всплывающем итоге.

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

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

Примечание

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

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

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

      изменения синхронизации с MicrosoftDocs/hololens на вилку.

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

      Щелкните изображение кнопки синхронизации.

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

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

    2. Сохранить изменения в Explorer.

      нажмите кнопку

    3. Зафиксировать все изменения в системы управления версиями (при появлении запроса на запись сообщения о фиксации).

      выберите системы управления версиями

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

      Нажмите кнопку синхронизации.

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

    Создать запрос на вытягивание из вилки в MicrosoftDocs/hololens.

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

Следующие расширения Visual Studio Code полезны при редактировании документации.

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

    • Поиск и ссылка на отправленные изображения.
    • Добавьте форматирование, например списки, таблицы и вызовы, такие как >[!NOTE].
    • Поиск и ссылка на внутренние ссылки и закладки (ссылки на определенные разделы на странице).
    • Ошибки форматирования выделены (наведите указатель мыши на ошибку, чтобы узнать больше).
  • средство проверки орфографии кода — слова с ошибкой будут подчеркиваться; Щелкните правой кнопкой мыши слово с ошибками, чтобы изменить его или сохранить его в словаре.