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

Контрольный список редактора

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

Метаданные

  • ms.date: должен быть в формате MM/DD/ГГГГ
    • Изменение даты при наличии значительного или фактического обновления
      • Реорганизация статьи
      • Устранение фактических ошибок
      • Добавление новых сведений
    • Не изменяйте дату, если обновление не является незначительным
      • Исправление опечаток и форматирование
  • title: уникальная строка длиной от 43 до 59 символов (включая пробелы)
    • Не включать идентификатор сайта (он создается автоматически)
    • Используйте вариант предложения— прописная буква только первого слова и любых правильных существительных
  • description: 115-145 символов, включая пробелы, — это абстрактное отображение в результатах поиска

Форматирование

  • Элементы синтаксиса backtick, которые отображаются встроенно внутри абзаца
    • Имена командлетов Verb-Noun
    • Переменная $counter
    • Синтаксические примеры Verb-Noun -Parameter
    • Пути к файлам C:\Program Files\PowerShell, /usr/bin/pwsh
    • URL-адреса, которые не предназначены для щелчка в документе
    • Значения свойств или параметров
  • Использование полужирного шрифта для имен свойств, имен параметров, имен классов, имен модулей, имен сущностей, объектов или имен типов
    • Полужирный шрифт используется для семантической разметки, а не выделения
    • Полужирный - используйте звездочки **
  • Курсивный шрифт — используйте подчеркивание _
    • Используется только для выделения, а не для семантической разметки
  • Разрывы строк в 100 столбцов (или в 80 для about_Topics)
  • Нет жестких вкладок. Используйте только пробелы
  • Отсутствие пробелов в конце строк
  • Ключевые слова и операторы PowerShell должны быть строчными.
  • Используйте правильный регистр (Pascal) для имен командлетов и параметров.

Заголовки

  • Сначала начните с H1 — только один H1 для каждой статьи
  • Используйте заголовки ATX только.
  • Использование варианта предложения для всех заголовков
  • Не пропускайте уровни - нет H3 без H2
  • Ограничение глубины заголовка до H3 или H4
  • Добавление пустых строк до и после
  • Не добавляйте и не удаляйте заголовки. PlatyPS применяет определенные заголовки в схеме.

Блоки кода

  • Добавление пустых строк до и после
  • Используйте обозначенные блоки кода — powershell, Output или другой соответствующий идентификатор языка
  • Используйте обрамление кода без тегов для блоков синтаксиса
  • Поместите выходные данные в отдельный блок кода, за исключением основных примеров, когда средство чтения не планирует использовать кнопку "Копировать "
  • Список поддерживаемых языков

Списки

  • Сделайте правильный отступ
  • Добавление пустых строк до первого элемента и после последнего элемента
  • Используйте дефис (-) для маркеров, а не звездочку (*), чтобы уменьшить путаницу с акцентом.
  • Использование 1. для всех элементов в нумерованном списке

Терминология

Примеры ссылок на командлеты

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

  • Примеры должны содержать лишь столько кода, чтобы демонстрировать использование.

  • Синтаксис PowerShell

    • Используйте полные имена командлетов и параметров — не используйте псевдонимы.
    • Используйте splatting для параметров, когда командная строка становится слишком длинной
    • Избегайте использования обратных кавычек для продолжения строк — используйте их только при необходимости

  • Удаление или упрощение запроса PowerShell (PS>за исключением случаев, когда это необходимо для примера)

  • Пример ссылки на командлет должен соответствовать следующей схеме PlatyPS

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • Не помещайте абзацы между блоками кода. Все описательное содержимое должно поступать до или после блоков кода.

Связывание с другими документами

  • При связывании вне набора документов или между ссылкой на командлет и концептуальной
    • Используйте URL-адреса относительно сайта при создании ссылок на Microsoft Learn (удалите https://learn.microsoft.com/en-us)
    • Не включать языковые параметры в URL-адреса на ресурсах Microsoft (удалите /en-us из URL-адреса)
    • Все URL-адреса внешних веб-сайтов должны использовать ПРОТОКОЛ HTTPS, если это не является допустимым для целевого сайта
  • При связывании в наборе документов
    • Используйте относительный файловый путь (../folder/file.md)
  • Все пути используют символы прямой наклонной черты (/)
  • Ссылки на изображения должны иметь уникальный замещающий текст