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

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

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

• Примеры форматирования кода
• Синтаксис команды форматирования
• Ссылки
• Линтинг Markdown
• Правописание

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

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

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

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

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

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

Ссылки

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

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

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

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

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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