Общие сведения о руководстве для участников документации По Microsoft Learn

Добро пожаловать в руководство для участников документации Microsoft Learn!

Обмен опытом с другими пользователями в Microsoft Learn помогает всем достичь большего. Используйте сведения в этом руководстве для публикации новой статьи в Microsoft Learn или внесения изменений в существующую опубликованную статью.

Некоторая документация корпорации Майкрософт предоставляется с открытым исходным кодом на портале GitHub. Не вся документация предоставляется с полностью открытым кодом, но многие документы размещены в общедоступных репозиториях, где вы можете предложить изменения с помощью запросов на вытягивание. Такой подход к открытому коду упрощает и улучшает взаимодействие между разработчиками продукта, командами по созданию содержимого и клиентами, а также обеспечивает ряд дополнительных преимуществ:

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

Пользовательский интерфейс в Microsoft Learn интегрирует рабочие процессы GitHub напрямую, чтобы сделать это еще проще. Для начала отредактируйте просматриваемый документ. Кроме того, вы можете помочь тем, что будете просматривать новые разделы или создавать отчеты о проблемах с качеством.

Важно!

Во всех репозиториях, публикуемых в Microsoft Learn, применяются Правила поведения с открытым исходным кодом Майкрософт или Правила поведения .NET Foundation. Дополнительные сведения см. на странице с часто задаваемыми вопросами о правилах поведения. С любыми вопросами или комментариями можно обратиться по адресу opencode@microsoft.com или conduct@dotnetfoundation.org.

Незначительные исправления или пояснения к документации и примерам кода в общедоступных репозиториях охватываются условиями использования learn.microsoft.com. Если новые или значительные изменения вносят не сотрудники корпорации Майкрософт, в комментариях к запросу на вытягивание появляется предложение принять условия лицензионного соглашения с участником (CLA). Вам нужно заполнить онлайн-форму, после чего мы сможем проверить или принять ваш запрос на вытягивание.

Быстрое редактирование документации

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

  1. Содержимое на некоторых страницах документов можно редактировать прямо в браузере. В таком случае вы увидите кнопку Edit (Изменить), как показано ниже. После нажатия кнопки Edit (Изменить) (или ее локализованного эквивалента) откроется исходный файл на GitHub.

    Расположение ссылки на изменение статьи.

    Если вы не видите кнопку Изменить, значит, содержимое не открыто для общедоступного редактирования. Некоторые страницы (например, из встроенной документации в коде) должны создаваться и редактироваться в проекте, к которому они относятся.

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

    Расположение значка вилки и карандаша для изменения.

  3. Измените файл в веб-редакторе. Откройте вкладку Предварительный просмотр, чтобы проверить форматирование изменений.

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

    Предложение и фиксация изменений в файлах.

  5. После предложения и фиксации изменений необходимо попросить владельцев репозитория вытянуть эти изменения в репозиторий. Это можно сделать с помощью так называемого запроса на вытягивание (PR). При нажатии кнопки Propose changes (Предложение изменений) откроется новая страница, похожая на приведенную ниже:

    Сравнение изменений и создание запроса на вытягивание.

    Щелкните Создать запрос на вытягивание. После этого введите название и описание запроса на вытягивание, а затем выберите Создать запрос на вытягивание. Если вы новичок на GitHub, обратитесь к дополнительным сведениям в статье О запросах на вытягивание.

  6. Вот и все! Участники команды по созданию содержимого проверят ваш запрос на вытягивание и выполнят слияние, когда он будет одобрен. Вы можете получить обратную связь с запросом изменений.

Пользовательский интерфейс редактирования сайта GitHub может реагировать по-разному в зависимости от ваших разрешений на работу с репозиторием. Предыдущие изображения предназначены для участников, которые не имеют разрешения на запись в целевом репозитории. GitHub автоматически создает вилку целевого репозитория в вашей учетной записи. По умолчанию имя новой вилки принимает формат GitHubUsername/RepositoryName. Если у вас есть права на запись в целевом репозитории, например в вилке, GitHub создает в нем новую ветвь. Имя ветви по умолчанию указано в формате patch-n с числовым идентификатором для ветви исправления.

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

Редактирование в браузере лучше использовать для незначительных и эпизодических изменений. Если вы вносите значительные изменения или используете расширенные возможности Git (например, управление ветвями или продвинутое разрешение конфликтов слияния), вам необходимо создать вилку репозитория и работать локально.

Примечание

В большинстве локализованных документов не предусмотрена возможность оставлять или изменять отзывы с помощью GitHub. Чтобы оставить отзыв о локализованном содержимом, используйте шаблон электронного письма, который доступен на странице aka.ms/DocSiteLocFeedback.

Проверка открытых запросов на вытягивание

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

Создание отчетов о проблемах с качеством

Мы постоянно работаем над улучшением нашей документации. Качественные запросы помогают нам сосредоточиться на наиболее приоритетных для сообщества направлениях. Чем больше информации мы получаем от вас, тем полезнее ваш запрос. Расскажите нам о том, какую информацию вы искали. Расскажите о том, какие условия поиска вы использовали. Если вы не знаете, с чего начать, расскажите о том, с чего вы хотели бы начать знакомство с новой технологией.

Большая часть документов корпорации Майкрософт содержит раздел Обратная связь в нижней части страницы. В этом разделе можно нажать кнопку Отзыв о продукте или Отзыв о содержимом, чтобы отследить проблемы, связанные с этой статьей.

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

Узнайте больше

Другие разделы этого руководства помогут вам приступить к эффективному участию в Работе с Microsoft Learn. Они описывают работу с репозиториями GitHub, средствами Markdown и расширениями, используемыми в содержимом Microsoft Learn.