Руководство для участников разработки документации Майкрософт. Общие сведенияMicrosoft Docs contributor guide overview

Добро пожаловать в руководство для участников docs.microsoft.com (Docs)!Welcome to the docs.microsoft.com (Docs) Contributor Guide!

Некоторая документация корпорации Майкрософт предоставляется с открытым исходным кодом на портале GitHub.Several of the Microsoft documentation sets are open source and hosted on GitHub. Не вся документация предоставляется с полностью открытым кодом, но многие документы размещены в общедоступных репозиториях, где вы можете создавать запросы на вытягивание.Not all document sets are completely open source but many have public-facing repos where you can make suggested changes via pull requests. Такой подход к открытому коду упрощает и улучшает взаимодействие между разработчиками продукта, командами по созданию содержимого и клиентами, а также обеспечивает ряд дополнительных преимуществ:This open source approach streamlines and improves communication between product engineers, content teams, and customers, and has other advantages:

  • Возможность открытого планирования содержимого репозиториев с такими текстами позволяет получать отзывы и определять наиболее востребованную документацию.Open source repos plan in the open to get feedback on what docs are most needed.
  • Возможность открытой проверки репозиториев с такими текстами позволяет гарантировать максимальную полезность содержимого при первой же публикации.Open source repos review in the open to publish the most helpful content on our first release.
  • Возможность открытой правки репозиториев с такими текстами позволяет упростить непрерывное совершенствование опубликованного содержимого.Open source repos update in the open to make it easier to continuously improve the content.

Пользовательский интерфейс сайта docs.microsoft.com непосредственно интегрирует рабочие процессы GitHub, делая их использование еще более удобными.The user experience on docs.microsoft.com integrates GitHub workflows directly to make it even easier. Для начала отредактируйте просматриваемый документ.Start by editing the document you are viewing. Кроме того, вы можете помочь тем, что будете просматривать новые разделы или создавать отчеты о проблемах с качеством.Or, help by reviewing new topics, or create quality issues.

Важно!

При работе со всеми репозиториями, используемыми для публикации на сайте docs.microsoft.com, необходимо соблюдать правила поведения для управляемых компанией Майкрософт сообществ разработки ПО с открытым кодом и правила поведения от .NET Foundation.All repositories that publish to docs.microsoft.com have adopted the Microsoft Open Source Code of Conduct or the .NET Foundation Code of Conduct. Дополнительные сведения см. на странице с часто задаваемыми вопросами о правилах поведения.For more information, see the Code of Conduct FAQ. С любыми вопросами и комментариями можно также обратиться по адресу opencode@microsoft.com или conduct@dotnetfoundation.org.Or contact opencode@microsoft.com, or conduct@dotnetfoundation.org with any questions or comments.

Порядок внесения незначительных изменений или уточнений в документацию и примеры кода из общедоступных репозиториев см. в условиях использования на сайте docs.microsoft.com.Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. Если новые или значительные изменения вносят не сотрудники корпорации Майкрософт, в комментариях к запросу на вытягивание появляется предложение принять условия лицензионного соглашения с участником (CLA).New or significant changes generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. Вам нужно заполнить онлайн-форму, после чего мы сможем проверить или принять ваш запрос на вытягивание.We need you to complete the online form before we can review or accept your pull request.

Быстрое редактирование существующей документацииQuick edits to existing documents

Быстрое редактирование позволяет оптимизировать отправку отчетов и устранение небольших ошибок и пропусков в документации.Quick edits streamline the process to report and fix small errors and omissions in documents. Несмотря на все прилагаемые усилия, в публикуемых документах, к сожалению, встречаются небольшие грамматические ошибки и опечатки.Despite all efforts, small grammar and spelling errors do make their way into our published documents. Вы можете создавать отчеты об ошибках, но быстрее и проще создать запрос на вытягивание, чтобы исправить ошибку, если есть такая возможность.While you can create issues to report mistakes, it's faster and easier to create a pull request (PR) to fix the issue, when the option is available.

  1. Содержимое на некоторых страницах документов можно редактировать прямо в браузере.Some docs pages allow you to edit content directly in the browser. В таком случае вы увидите кнопку Edit (Изменить), как показано ниже.If so, you'll see an Edit button like the one shown below. При нажатии Edit (или ее локализованного варианта) откроется исходный файл на GitHub.Clicking the Edit (or equivalently localized) button takes you to the source file on GitHub. Если кнопка Изменить не отображается, значит страницу документа нельзя редактировать.If the Edit button is missing, that means the documentation page is not available to be changed.

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

  2. Щелкните значок карандаша, чтобы отредактировать статью.Next, click the pencil icon, to edit the article as shown. Если значок карандаша показан серым, войдите в свою учетную запись GitHub или создайте новую.If the pencil icon is grayed out, you need to either log in to your GitHub account or create a new account.

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

  3. Внесите необходимые изменения в веб-редакторе.Make your changes in the web editor. Щелкните вкладку Preview changes (Предварительный просмотр изменений), чтобы проверить форматирование измененного текста.Click the Preview changes tab to check the formatting of your change.

  4. Закончив вносить изменения, прокрутите страницу вниз до конца.Once you have made your changes, scroll to the bottom of the page. Введите заголовок и описание изменений и нажмите кнопку Propose file change (Предложить изменение файла), как показано на рисунке ниже:Enter a title and description for your changes and click Propose file change as shown in the following figure:

    Propose file change (Предложить изменение файла)

  5. Предложив изменения, необходимо попросить владельцев репозитория вытянуть эти изменения в репозиторий.Now that you've proposed your change, you need to ask the owners of the repository to "pull" your changes into their repository. Это можно сделать с помощью так называемого запроса на вытягивание.This is done using something called a "pull request". После нажатия кнопки Propose file change (Предложить изменение файла), изображенной на рисунке выше, должна открыться новая страница, как на рисунке ниже:When you clicked on Propose file change in the figure above, you should have been taken to a new page that looks like the following figure:

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

    Нажмите кнопку Create pull request (Создать запрос на вытягивание), введите имя (и при необходимости описание) запроса на вытягивание, а затем снова нажмите кнопку Create pull request (Создать запрос на вытягивание).Click Create pull request, enter a title (and optionally a description) for the pull request, and then click Create pull request again. Если вы новичок на GitHub, см. дополнительные сведения в статье About Pull Requests (О запросах на вытягивание).(If you are new to GitHub, see About Pull Requests for more information.)

  6. Вот и все!That's it! Участники команды по созданию содержимого проверят ваш запрос на вытягивание и выполнят слияние.Content team members will review and merge your PR. Вы можете получить ответ с просьбой отредактировать изменения, если вы внесли значительные правки.You may get some feedback requesting changes if you made larger changes.

Пользовательский интерфейс редактирования сайта GitHub может реагировать по-разному в зависимости от ваших разрешений на работу с репозиторием.The GitHub editing UI responds to your permissions on the repository. Предыдущие рисунки актуальны для участников, которые не имеют разрешения на запись в целевом репозитории.The preceding images are accurate for contributors that do not have write permissions to the target repository. GitHub автоматически создает вилку целевого репозитория в вашей учетной записи.GitHub automatically creates a fork of the target repository in your account. Если у вас есть права на запись в целевом репозитории, GitHub создает в нем новую ветвь.If you have write-access to the target repository, GitHub creates a new branch in the target repo. Имя ветви указано в формате <GitHubId>-patch-n, где GitHubId — ваш идентификатор на сайте GitHub, а patch-n — числовой идентификатор для ветви исправления.The branch name has the form <GitHubId>-patch-n using your GitHub ID, and a numeric identifier for the patch branch.

Для всех изменений используются запросы на вытягивание, даже если вносящий их участник имеет права на запись.We use pull requests for all changes, even for contributors that have write-access. В большинстве репозиториев ветвь master защищена, так что обновления должны отправляться в виде запросов на вытягивание.Most repositories have the master branch protected so that updates must be submitted as pull requests.

Редактирование в браузере лучше использовать для незначительных и эпизодических изменений.The in-browser editing experience is best for minor or infrequent changes. Если вы вносите значительные изменения или используете расширенные возможности Git (например, управление ветвями или продвинутое разрешение конфликтов слияния), вам необходимо создать вилку репозитория и работать локально.If you make large contributions or use advanced Git features (such as branch management or advanced merge conflict resolution), you need to fork the repo and work locally.

Примечание

Если эта функция включена, вы можете редактировать статью на любом языке, и в зависимости от типа редактирования результаты будет следующими:If enabled, you can edit an article in any language and, based on the type of edit, the following will happen:

  1. Любые утвержденные лингвистические изменения помогут улучшить нашу систему машинного перевода.any linguistic change that is approved, will also help improve our Machine Translation engine
  2. В случае утверждения каких-то значительных изменений содержимого статьи эти изменения будут переданы на внутреннюю обработку, а затем внесены в англоязычную версию статьи и впоследствии локализованы на все прочие языки.any edit that significantly modifies the content of the article will be handled internally to submit a change to the same article in English so that it will get localized in all languages if approved. Таким образом, предложенные вами изменения помогут улучшить статью не только на вашем, но и на всех доступных языках.Your suggested improvements will not only positively affect articles in your own language, but in all available languages.

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

Вы можете просматривать новые разделы до их публикации, проверяя открытые запросы на вытягивание.You can read new topics before they are published by checking the currently open PRs. Проверки выполняются в соответствии с процедурой GitHub.Reviews follow the GitHub flow process. Предложенные обновления и новые статьи можно увидеть в общедоступных репозиториях.You can see proposed updates or new articles in public repositories. Вы можете проверять их и добавлять комментарии.Review them and add your comments. Просматривайте любые наши репозитории с документацией и открытые запросы на вытягивание с интересующей вас тематикой.Look at any of our docs repositories, and check the open pull requests (PRs) for areas that interest you. Отзывы пользователей о предлагаемых обновлениях идут на пользу всему сообществу.Community feedback on proposed updates helps the entire community.

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

Мы постоянно работаем над улучшением нашей документации.Our docs are a continuous work in progress. Качественные запросы помогают нам сосредоточиться на наиболее приоритетных для сообщества направлениях.Good issues help us focus our efforts on the highest priorities for the community. Чем больше информации мы получаем от вас, тем полезнее ваш запрос.The more detail you can provide, the more helpful the issue. Расскажите нам о том, какую информацию вы искали.Tell us what information you sought. Расскажите о том, какие условия поиска вы использовали.Tell us the search terms you used. Если вы не знаете, с чего начать, расскажите о том, с чего вы хотели бы начать знакомство с новой технологией.If you can't get started, tell us how you want to start exploring unfamiliar technology.

Большая часть документов корпорации Майкрософт содержит раздел Обратная связь в нижней части страницы. В этом разделе можно нажать кнопку Отзыв о продукте или Отзыв о содержимом, чтобы отследить проблемы, связанные с этой статьей.Many of Microsoft's documentation pages have a Feedback section at the bottom of the page where you can click to leave Product feedback or Content feedback to track issues that are specific to that article.

Чтобы понять ваши потребности, нам необходимы ваши отзывы.Issues start the conversation about what's needed. Команда по созданию содержимого ответит на эти запросы, предложив возможные варианты решения, и поинтересуется вашим мнением.The content team will respond to these issues with ideas for what we can add, and ask for your opinions. Когда проект решения будет готов, мы попросим вас проверить запрос на вытягивание.When we create a draft, we'll ask you to review the PR.

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

В других разделах представлена информация, которая поможет вам стать участником и внести свой вклад в развитие документации Майкрософт. В них разъясняются принципы работы с репозиториями GitHub, средствами Markdown и расширениями, используемыми на платформе документации Майкрософт.Other topics help you get started productively contributing to Microsoft Docs. They explain working with GitHub repositories, Markdown tools, and extensions used in the Microsoft Docs platform.