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

Начните вносить вклад в документацию по PowerShell

В этой статье приводится обзор того, как начать вносить вклад в документацию по PowerShell.

структура PowerShell-Docs

В репозитории PowerShell-Docs есть три категории содержимого:

  • справочное содержимое
  • концептуальное содержимое
  • метаданные и файлы конфигурации

Справочные материалы

Эталонное содержимое — это справочник по командлетам PowerShell для командлетов, которые входят в состав PowerShell. Командлет ссылки хранится в версированных папках (например, 5.1, 7.4, 7.5 и 7.6), в которых содержатся ссылки на модули, поставляемые с PowerShell. Это содержимое также используется для создания справочной информации, отображаемой командлетом Get-Help.

Концептуальное содержимое

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

Заметка

При каждом добавлении, удалении или переименовании концептуальной статьи необходимо обновить TOC. Все удаленные или переименованные файлы должны быть перенаправлены.

Файлы метаданных

Этот проект содержит несколько типов файлов метаданных. Файлы метаданных управляют поведением наших средств сборки и системы публикации. Только PowerShell-Docs обслуживающие и утвержденные участники могут изменять эти файлы. Если вы считаете, что метафайл должен быть изменен, откройте проблему, чтобы обсудить необходимые изменения.

Метафайлы в корневом каталоге репозитория

  • .* — файлы конфигурации в корневом каталоге репозитория
  • *.md . Документация по проекту в корневом каталоге репозитория
  • *.yml . Документация по проекту в корневом каталоге репозитория
  • .devcontainer/* — файлы конфигурации devcontainer
  • .github/**/* — шаблоны, действия и другие метафайлы GitHub
  • .vscode/**/* — конфигурации расширения VS Code
  • assets/* — содержит скачиваемые файлы, которые упоминаются в документации
  • redir/* — содержит файлы сопоставления перенаправления
  • tests/* — средства тестирования, используемые системой сборки
  • tools/* — другие средства, используемые системой сборки

Метафайлы в наборе документации

  • reference/**/*.json — конфигурационные файлы docset
  • reference/**/*.yml — TOC и другие структурированные файлы содержимого
  • reference/bread/* — настройка навигации с хлебными крошками
  • reference/includes/* — файлы включения markdown
  • reference/mapping/* — конфигурация сопоставления версий
  • reference/**/media/** — файлы изображений, используемые в документации
  • reference/module/* — настройка страницы браузера модуля

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

Для каждого нового документа, который вы хотите внести, нужно создать заявку на GitHub. Проверьте наличие существующих проблем, чтобы убедиться, что вы не дублируете усилия. Назначенные задачи имеют статус in progress. Если вы хотите сотрудничать по вопросу, обратитесь к ответственному за данный вопрос.

Как и в процессе RFC PowerShell, создайте задачу перед написанием содержимого. Проблема гарантирует, что вы не тратите время и усилия на работу, которая отклоняется командой PowerShell-Docs. Эта проблема позволяет нам обсудить с вами содержание и его место в документации по PowerShell. Все статьи должны быть включены в оглавление (TOC). Предлагаемое расположение TOC должно быть включено в обсуждение вопроса.

Заметка

Система публикации автоматически создает Оглавление для справочных материалов. Вам не нужно обновлять TOC.

Обновление существующих статей

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

Примените соответствующее изменение к каждой версии файла.

Локализованное содержимое

Документация По PowerShell написана на английском языке и переведена на 17 других языков. Содержимое английского языка хранится в репозитории GitHub с именем MicrosoftDocs/PowerShell-Docs. Проблемы, обнаруженные в преобразованном содержимом, должны быть отправлены в этот репозиторий.

Сначала все переводы начинаются с английского содержимого. Мы используем как человеческий, так и машинный перевод.

Метод перевода Языки
Человеческий перевод de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Машинный перевод cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

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

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

Дальнейшие действия

Существует два распространенных способа отправки изменений в GitHub. Оба метода описаны в Центральном руководстве участника:

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

Прежде чем начинать любые изменения, необходимо создать форк репозитория PowerShell-Docs. Изменения должны быть внесены в рабочую ветвь в копии PowerShell-Docs. Если вы используете метод быстрого редактирования в GitHub, эти действия обрабатываются для вас. Если вы используете полный рабочий процесс GitHub, необходимо настроиться для локальной работы.

Оба метода заканчиваются созданием Pull Request (PR). Дополнительные сведения и рекомендации см. в разделе "Отправка запроса на вытягивание".