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

Вклад в повышение качества.

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

Мы сосредоточимся на этих областях качества:

Отслеживание проектов

Мы отслеживаем вклад с помощью проекта GitHub PowerShell Docs Quality Contributions.

На странице проекта есть несколько представлений для проблем и PR, связанных с этим усилием:

Примеры форматирования кода

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

  • Все блоки кода должны содержаться в ограждении кода с тремя обратными кавычками (```).
  • Длина строки для блоков кода в справочных статьях о командлетах ограничена 90 символами.
  • Длина строки для блоков кода ограничена 76 символами для about_* статей.
  • Избегайте использования символов продолжения строки (`) в примерах кода PowerShell.
    • Используйте возможности сплетирования или естественного разрыва линий, например после символов канала| (), открывая скобки (}), скобки () и скобки (([), чтобы ограничить длину линии.
  • Включайте только строку команд PowerShell для иллюстративных примеров, в которых код не предназначен для копирования и вставки.
  • Не используйте псевдонимы в примерах, если вы не документируете их специально.
  • Избегайте использования позиционных параметров. Используйте имя параметра, даже если параметр позициональный.

Синтаксис команды форматирования

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

  • Всегда используйте полное имя командлетов и параметров. Избегайте использования псевдонимов, если вы специально не демонстрируете псевдоним.
  • Свойство, параметр, объект, имена типов, имена классов, методы класса должны быть полужирным шрифтом.
    • Значения свойств и параметров должны быть заключены в обратные кавычки (`).
    • При обращении к типам с помощью стиля со скобками используйте обратные апострофы. Например: [System.Io.FileInfo]
  • Имена модулей PowerShell должны быть полужирным шрифтом.
  • Ключевые слова и операторы PowerShell должны быть в нижнем регистре.
  • Используйте правильный регистр (Pascal) для имен и параметров командлетов.
  • При обращении к параметру по имени, имя должно быть полужирным.
  • Используйте имя параметра с дефисом, если вы иллюстрируете синтаксис. Обрамите параметр в обратные кавычки.
  • При показе примера использования внешней команды, пример должен быть заключён в символы обратной кавычки. Всегда указывайте расширение файла для внешней команды.

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

Например, вместо:

The [Packages tab][31] displays all available
packages in the PowerShell Gallery.

Это должно быть:

The [Packages tab][31] displays all available packages in the PowerShell Gallery.

Примечание.

При замене встроенной ссылки переформатируйте содержимое, чтобы его строки размещались по 100 символов. Расширение VS Code reflow-markdown можно использовать для быстрого перераспределения абзаца.

В нижней части файла добавьте комментарий markdown перед определением ссылок.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Убедитесь, что:

  1. Ссылки определяются в том порядке, в который они отображаются в документе.
  2. Каждая ссылка указывает на правильное расположение.
  3. Определения ссылок находятся в нижней части файла после комментария markdown и находятся в правильном порядке.

Проверка синтаксиса Markdown

Для любой статьи в одном из участвующих репозиториев, открытие статьи в VS Code отображает предупреждения линтинга. Рассмотрите любые из этих предупреждений, за исключением:

  • MD022/blanks-around-headings/blanks-around-headers для заголовка Synopsis в справочных документах командлета. Для этих элементов нарушение правил является намеренным, чтобы гарантировать правильную сборку документации с использованием PlatyPS.

Убедитесь, что длины строк корректны, и используйте расширение Reflow Markdown для исправления любых длинных строк.

Правописание

Несмотря на все наши усилия, опечатки и орфографические ошибки проскакивают и в конечном итоге попадают в документацию. Эти ошибки затрудняют понимание и локализацию документации. Исправление этих ошибок делает документацию более читаемой, особенно для неанглаговорящих, которые полагаются на точные переводы.

Процедура

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

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

  2. Откройте новую проблему в соответствующем репозитории:

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

  4. Отправьте пулреквест. Убедитесь:

    1. Заголовок PR имеет Quality: префикс.

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

      Например, если вы работаете над проблемой 123, текст вашего PR должен включать следующий Markdown:

      - resolves #123

    После отправки PR, участники будут проверять вашу работу и работать с вами, чтобы его объединить.