Skip to content

Latest commit

 

History

History
123 lines (99 loc) · 4.52 KB

editorial-checklist.md

File metadata and controls

123 lines (99 loc) · 4.52 KB
description ms.date title
This article contains a summarized list of rules for editing PowerShell documentation.
03/30/2025
Editorial checklist

Editor's checklist

This article contains a summarized list of rules for writing or editing PowerShell documentation. See other articles in the Contributor's Guide for detailed explanations and examples of these rules.

Metadata

  • ms.date: must be in the format MM/DD/YYYY
    • Change the date when there's a significant or factual update
      • Reorganizing the article
      • Fixing factual errors
      • Adding new information
    • Don't change the date if the update is insignificant
      • Fixing typos and formatting
  • title: unique string of 43-59 characters long (including spaces)
    • Don't include site identifier (it's autogenerated)
    • Use sentence case - capitalize only the first word and any proper nouns
  • description: 115-145 characters including spaces - this abstract displays in the search result

Formatting

  • Backtick syntax elements that appear, inline, within a paragraph
    • Cmdlet names Verb-Noun
    • Variable $counter
    • Syntactic examples Verb-Noun -Parameter
    • File paths C:\Program Files\PowerShell, /usr/bin/pwsh
    • URLs that aren't meant to be clickable in the document
    • Property or parameter values
  • Use bold for property names, parameter names, class names, module names, entity names, object, or type names
    • Bold is used for semantic markup, not emphasis
    • Bold - use asterisks **
  • Italic - use underscore _
    • Only used for emphasis, not for semantic markup
  • Line breaks at 100 columns (or at 80 for about_Topics)
  • No hard tabs - use spaces only
  • No trailing spaces on lines
  • PowerShell keywords and operators should be all lowercase
  • Use proper (Pascal) casing for cmdlet names and parameters

Headers

  • Start with H1 first - only one H1 per article
  • Use ATX Headers only
  • Use sentence case for all headers
  • Don't skip levels - no H3 without an H2
  • Limit header depth to H3 or H4
  • Add blank lines before and after
  • Don't add or remove headers - PlatyPS enforces specific headers in its schema

Code blocks

  • Add blank lines before and after
  • Use tagged code fences - powershell, Output, or other appropriate language ID
  • Use untagged code fence for syntax blocks
  • Put output in separate code block except for basic examples where you don't intend for the reader to use the Copy button
  • See list of supported languages

Lists

  • Indent properly
  • Add blank lines before first item and after last item
  • Use hyphen (-) for bullets not asterisk (*) to reduce confusion with emphasis
  • Use 1. for all items in a numbered list

Terminology

Cmdlet reference examples

  • Must have at least one example in cmdlet reference

  • Examples should be only enough code to demonstrate the usage

  • PowerShell syntax

    • Use full names of cmdlets and parameters - no aliases
    • Use splatting for parameters when the command line gets too long
    • Avoid using line continuation backticks - only use when necessary

  • Remove or simplify the PowerShell prompt (PS>) except where required for the example

  • Cmdlet reference example must follow the following PlatyPS schema

    ### 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.

  • don't put paragraphs between the code blocks. All descriptive content must come before or after the code blocks.

Linking to other documents

  • When linking outside the docset or between cmdlet reference and conceptual
    • Use site-relative URLs when linking to Microsoft Learn (remove https://learn.microsoft.com/en-us)
    • don't include locales in URLs on Microsoft properties (remove /en-us from URL)
    • All URLs to external websites should use HTTPS unless that's not valid for the target site
  • When linking within the docset
    • Use the relative filepath (../folder/file.md)
  • All paths use forward-slash (/) characters
  • Image links should have unique alt text