Dela via

Redigerarens checklista

Den här artikeln innehåller en sammanfattad lista över regler för att skriva eller redigera PowerShell-dokumentation. Se andra artiklar i deltagarguiden för detaljerade förklaringar och exempel på dessa regler.

Metainformation

  • ms.date: måste ha formatet MM/DD/ÅÅÅÅ
    • Ändra datumet när det finns en betydande eller faktisk uppdatering
      • Omorganisera artikeln
      • Åtgärda faktafel
      • Lägga till ny information
    • Ändra inte datumet om uppdateringen är obetydlig
      • Åtgärda stavfel och formatering
  • title: unik sträng med 43–59 tecken lång (inklusive blanksteg)
    • Inkludera inte platsidentifierare (den genereras automatiskt)
    • Använd meningsfall – versalisera endast det första ordet och eventuella lämpliga substantiv
  • description: 115–145 tecken inklusive blanksteg – den här sammanfattningen visas i sökresultatet

Formatera

  • Backtick-syntaxelement som visas infogade i ett stycke
    • Cmdlet-namn Verb-Noun
    • Variabel $counter
    • Syntaktiska exempel Verb-Noun -Parameter
    • Filsökvägar C:\Program Files\PowerShell, /usr/bin/pwsh
    • URL:er som inte är avsedda att vara klickbara i dokumentet
    • Egenskaps- eller parametervärden
  • Använd fetstil för egenskapsnamn, parameternamn, klassnamn, modulnamn, entitetsnamn, objekt eller typnamn
    • Fetstil används för semantisk markering, inte betoning
    • Fetstil – använd asterisker **
  • Kursiv – använd understreck _
    • Används endast för betoning, inte för semantisk markering
  • Radbrytningar vid 100 kolumner (eller vid 80 för about_Topics)
  • Inga hårda flikar – använd endast blanksteg
  • Inga avslutande blanksteg på linjer
  • Nyckelord och operatorer i PowerShell bör vara gemener
  • Använd rätt (Pascal)-hölje för cmdlet-namn och parametrar

Rubriker

  • Börja med H1 först – endast en H1 per artikel
  • Använd endast ATX-rubriker
  • Använd meningsfall för alla rubriker
  • Hoppa inte över nivåer – ingen H3 utan H2
  • Begränsa sidhuvuddjup till H3 eller H4
  • Lägg till tomma rader före och efter
  • Lägg inte till eller ta bort rubriker – PlatyPS framtvingar specifika rubriker i schemat

Kodblock

  • Lägg till tomma rader före och efter
  • Använda taggade kodstängsel – powershell, utdata eller annat lämpligt språk-ID
  • Använda otaggade kodstängsel för syntaxblock
  • Placera utdata i ett separat kodblock förutom grundläggande exempel där du inte tänker att läsaren ska använda knappen Kopiera
  • Se en lista över språk som stöds

Listor

  • Indrag ordentligt
  • Lägg till tomma rader före det första objektet och efter det sista objektet
  • Använd bindestreck (-) för punkter som inte är asterisk (*) för att minska förvirring med betoning
  • Använd 1. för alla objekt i en numrerad lista

Terminologi

Cmdlet-referensexempel

  • Måste ha minst ett exempel i cmdlet-referens

  • Exempel bör bara vara tillräckligt med kod för att demonstrera användningen

  • PowerShell-syntax

    • Använd fullständiga namn på cmdletar och parametrar – inga alias
    • Använd splatting för parametrar när kommandoraden blir för lång
    • Undvik att använda backticks för linjefortsättning – använd endast när det behövs

  • Ta bort eller förenkla PowerShell-prompten (PS>) förutom när det krävs för exemplet

  • Cmdlet-referensexemplet måste följa följande 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.

  • placera inte stycken mellan kodblocken. Allt beskrivande innehåll måste komma före eller efter kodblocken.

Länka till andra dokument

  • När du länkar utanför dokumentuppsättningen eller mellan cmdlet-referens och konceptuell
    • Använda webbplatsrelativa URL:er när du länkar till Microsoft Learn (ta bort https://learn.microsoft.com/en-us)
    • ta inte med nationella inställningar i URL:er på Microsoft-egenskaper (ta bort /en-us från URL)
    • Alla URL:er till externa webbplatser bör använda HTTPS om det inte är giltigt för målwebbplatsen
  • När du länkar inom dokumentationssetet
    • Använd den relativa filsökvägen (../folder/file.md)
  • Alla sökvägar använder snedstreck (/) tecken
  • Bildlänkar ska ha unik alternativtext
  • Last updated on