Edit

Share via

Editor's checklist

  • Article

This is a summary of rules to apply when writing new or updating existing articles. 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 is 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

  • H1 is 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
  • Max depth of H3 or H4
  • Blank line before and after
  • PlatyPS enforces specific headers in its schema - don't add or remove headers

Code blocks

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

Lists

  • Indented properly
  • Blank line before first item and after last item
  • Bullet - use hyphen (-) not asterisk (*) to reduce confusion with emphasis
  • For numbered lists, all numbers are "1."

Terminology

Cmdlet reference examples

  • Must have at least one example in cmdlet reference

  • Examples should be just 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 (eg. 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 (e.g. ../folder/file.md)
  • All paths use forward-slash (/) characters
  • Image links should have unique alt text