den-kozlov/azure-docs.ru-ru

Правила поведения Майкрософт при работе с проектами с открытым кодом

Этот проект соответствует правилам поведения Microsoft Open Source. Дополнительные сведения см. на странице Вопросы и ответы о правилах поведения или отправьте вопросы и комментарии по адресу opencode@microsoft.com.

Руководство для пользователей, участвующих в редактировании технической документации Azure

Вы находитесь в репозитории GitHub. Здесь хранится техническая документация Azure, публикуемая по адресу https://docs.microsoft.com/azure.

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

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

Благодарим вас за проявленный интерес к документации Azure.

• Варианты участия в наполнении документации
• Правила поведения
• Внесение изменений в содержимое Azure
• Организация репозитория
• Использование GitHub, Git и этого репозитория
• Использование разметки Markdown для форматирования статьи
• Дополнительные ресурсы
• Указатель всех статей руководства для пользователей, участвующих в редактировании документации (открывается новая страница)

Варианты участия в наполнении документации

Вносить изменения в документацию Azure можно следующим образом.

• Редактируйте технические статьи через пользовательский интерфейс GitHub. Найдите нужную статью в этом репозитории или откройте ее на странице https://docs.microsoft.com/azure и щелкните ссылку на источник в репозитории GitHub.
• Если вы вносите значительные изменения в существующую статью, добавляете или изменяете изображения либо создаете статью, вам необходимо создать полную локальную копию репозитория (форк), установить Git Bash и Markdown Pad, а также изучить некоторые команды git.

Внесение изменений в содержимое Azure

Незначительные исправления

Порядок внесения незначительных исправлений или уточнений в документацию и примеры кода из этого репозитория описаны в условиях использования на сайте docs.microsoft.com.

Значительные изменения

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

Организация репозитория

Содержимое в репозитории azure-docs организовано так же, как и документация на странице https://docs.microsoft.com/azure. Этот репозиторий содержит две корневые папки.

\articles

В папке \articles содержатся статьи в формате Markdown (файлы с расширением MD). Обычно статьи группируются по службе Azure.

Названия статей должны соответствовать строгим правилам именования файлов. Дополнительные сведения см. в руководстве по именованию файлов.

Папка \articles содержит папку \media, предназначенную для файлов мультимедиа из статей корневого каталога. В ней хранятся вложенные папки с изображениями для каждой статьи. В служебных папках есть отдельная папка media для статей из каждой служебной папки. Папка с изображениями для статьи называется так же, как и файл статьи, но без расширения MD.

\includes

Вы можете создавать содержимое, которое будет использоваться в нескольких статьях. См. статью Custom extensions used in our technical content (Пользовательские расширения, используемые в наших технических статьях).

\markdown templates

Эта папка содержит наш стандартный шаблон с основными элементами разметки Markdown, которые могут понадобиться для форматирования статьи.

\contributor-guide

В этой папке хранятся статьи, которые относятся к руководству по редактированию документации.

Использование GitHub, Git и этого репозитория

Сведения о том, как участвовать в редактировании, вносить небольшие изменения с помощью пользовательского интерфейса GitHub, создавать полные локальные копии репозитория (форк) или клонировать его для более значительных изменений, см. в статье Install and set up tools for authoring in GitHub (Установка и настройка средств для создания документации в GitHub).

Если вы установили GitBash и работаете локально, шаги по созданию новой локальной ветви, внесению изменений и их отправке обратно в главную ветвь см. в статье Git commands for creating a new article or updating an existing article (Команды Git для создания статьи или обновления имеющейся).

Ветви

Мы рекомендуем создавать локальные рабочие ветви, в которые входит только определенный тип изменений. Каждая ветвь должна относиться только к одной концепции или статье, что позволит не только оптимизировать рабочий процесс, но и снизить вероятность конфликтов при слиянии. Вот несколько примеров случаев, когда целесообразно создавать ветвь:

• добавление статьи (и связанных с ней изображений);
• исправление орфографических и грамматических ошибок в статье;
• унификация форматирования в большом наборе статей (например, добавление нового нижнего колонтитула с информацией об авторских правах).

Использование разметки Markdown для форматирования статьи

Во всех статьях в этом репозитории используется разметка Markdown, принятая для GitHub. Вот список полезных ресурсов:

• Основные сведения о разметке Markdown.
• Подсказки по разметке Markdown в печатном формате.

Метаданные статьи

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

Метки

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

• Метки, связанные с лицензионным соглашением участника:
  • cla-not-required — относительно небольшое изменение, не требующее принятия условий CLA;
  • cla-required — достаточно большая область изменений, требующая принятия условий CLA;
  • cla-signed — участник принял условия CLA, в результате чего запрос на включение внесенных изменений можно отправить для проверки.
• Метки компонентов — метки, такие как PnP, Modern Apps и TDC, позволяющие группировать запросы на включение внесенных изменений по внутренней организации, для которой нужно проверить запрос.
• Изменения, отправленные автору, — автор получает уведомление о запросе на включение внесенных изменений.

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

Список всех статей этого руководства приведен в указателе.