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

Руководство по созданию документации для командлетов PowerShell

  • Статья

Командлеты PowerShell могут быть полезными, но если разделы справки четко не объясняют, что делает командлет и как его использовать, командлет может не использоваться или, еще хуже, это может привести к разочарованию пользователей. Формат файла справки на основе XML улучшает согласованность, но большая помощь требует гораздо большего.

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

Руководство по написанию рекомендаций для справки по командлетам

Хорошо написать

Ничего не заменяет хорошо написанную тему. Если вы не профессиональный писатель, найдите писателя или редактора, чтобы помочь вам. Другой альтернативой является копирование текста справки в Microsoft Word и использование проверок грамматики и орфографии для улучшения работы.

Просто написать

Используйте простые слова и фразы. Избегайте жаргона. Учитывайте, что многие читатели оснащены только словарем иностранного языка и разделом справки.

Последовательная запись

Справка по связанным командлетам должна быть аналогична (например, Get-Content и Set-Content). Используйте стандартные описания стандартных параметров, таких как Force и InputObject. (Скопируйте их из справки для основных командлетов.) Используйте стандартные термины. Например, используйте "parameter", а не "argument" и используйте "командлет" не "command" или "command-let".

Запуск синопсиса с помощью команды

Поле synopsis сообщает пользователю, что делает командлет, а не то, что это или как это работает. Команды создают инструкцию на основе задач, которая сообщает пользователям, соответствует ли этот командлет своим требованиям. Используйте простые команды, такие как get, create и change. Избегайте "set", которые могут быть расплывчатыми и фантазийными словами, такими как "изменить".

Фокус на объектах

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

Написание подробных описаний

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

Использование обычного синтаксиса

Используйте стандартный формат Backus-Naur, который является общим для справки командной строки Windows и Unix.

Использование типов Microsoft .NET для значений параметров

Заполнители для значений параметров (в синтаксисе и описаниях параметров) отображают типы объектов .NET Framework, которые будет принимать параметр. Команда PowerShell разработала это соглашение, чтобы научить пользователей .NET Framework.

Написание полных описаний параметров

Описания параметров должны информировать пользователей о двух вещах: о том, что делает параметр (его эффект) и что они должны ввести для значений параметров.

Написание практических примеров

Примеры должны показать, как использовать все параметры, но самое главное — показать, как использовать командлет в реальных задачах. Начните с простого примера и напишите все более сложные примеры. В последнем примере показано, как использовать командлет в конвейере.

Использование поля "Заметки"

Используйте поле "Заметки", чтобы объяснить основные понятия, которые пользователи должны понимать командлет. Вы также можете использовать заметки, чтобы помочь пользователям избежать распространенных ошибок. Избегайте URL-адресов по мере их изменения. Вместо этого предоставьте пользователям условия поиска.

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

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

См. также