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

• Use PowerShell vs. Windows PowerShell
• See Product 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