Kontrolní seznam editoru

Tento článek obsahuje souhrnný seznam pravidel pro psaní nebo úpravy dokumentace k PowerShellu. Podrobné vysvětlení a příklady těchto pravidel najdete v dalších článcích v příručce pro přispěvatele.

Metadatové údaje

  • ms.date: musí být ve formátu MM/DD/RRRR
    • Změna data, kdy dojde k významné nebo faktické aktualizaci
      • Změna uspořádání článku
      • Oprava faktických chyb
      • Přidání nových informací
    • Neměňte datum, pokud je aktualizace nevýznamná.
      • Oprava překlepů a formátování
  • title: jedinečný řetězec s délkou 43–59 znaků (včetně mezer)
    • Nezahrnujte identifikátor webu (je automaticky vygenerovaný).
    • Používejte větné písmo - kapitalizujte pouze první slovo a všechna vlastní jména
  • description: 115-145 znaků včetně mezer – tato abstrakce se zobrazí ve výsledku hledání.

Formátování

  • Prvky syntaxe backtick, které se zobrazí v textu odstavce
    • Názvy rutin Verb-Noun
    • Proměnná $counter
    • Syntaktické příklady Verb-Noun -Parameter
    • Cesty k souborům C:\Program Files\PowerShell, /usr/bin/pwsh
    • Adresy URL, které nemají být v dokumentu kliknutelné
    • Hodnoty vlastností nebo parametrů
  • Použijte tučné písmo pro názvy vlastností, názvy parametrů, názvy tříd, názvy modulů, názvy entit, objekt nebo názvy typů.
    • Tučné písmo se používá pro sémantické značky, nezvýrazní se
    • Tučné písmo – použití hvězdičky **
  • Kurzíva – použití podtržítka _
    • Používá se pouze pro zdůraznění, ne pro sémantické označení.
  • Konce řádků na 100 sloupcích (nebo 80 pro about_Topics)
  • Žádné pevné tabulátory – používejte jenom mezery.
  • Žádné koncové mezery na řádcích
  • Klíčová slova a operátory PowerShellu by měly být malými písmeny.
  • Použití správného písmena (Pascal) pro názvy a parametry rutin

Hlavičky

  • Nejprve začněte s H1 – pouze jeden H1 na článek
  • Používejte pouze hlavičky ATX
  • Použijte větný styl pro všechna záhlaví
  • Nepřeskakujte úrovně – žádné H3 bez předchozího H2
  • Omezení hloubky záhlaví na H3 nebo H4
  • Přidání prázdných řádků před a za
  • Nepřidávejte ani neodebívejte hlavičky – PlatyPS vynucuje konkrétní hlavičky ve schématu.

Bloky kódu

  • Přidání prázdných řádků před a za
  • Použijte ohraničení kódu se značkami – powershell, Výstup nebo další vhodné jazykové ID
  • Použijte neočíslované ohraničení kódu pro syntaktické bloky
  • Vložte výstup do samostatného bloku kódu s výjimkou základních příkladů, ve kterých nemáte v úmyslu čtenáře použít tlačítko Kopírovat .
  • Zobrazit seznam podporovaných jazyků

Seznamy

  • Odsadit správně
  • Přidání prázdných řádků před první položku a za poslední položku
  • Použijte spojovník (-) místo hvězdičky (*) pro odrážky, abyste snížili záměnu s důrazem.
  • Použijte 1. pro všechny položky v číslovaném seznamu.

Terminologie

Referenční příklady rutin

  • V referenčních informacích k rutině musí být alespoň jeden příklad.

  • Příklady by měly být dostatečné pouze pro předvedení využití.

  • Syntaxe PowerShellu

    • Použití úplných názvů rutin a parametrů – žádné aliasy
    • Použití splattingu pro parametry v případě, že příkazový řádek je příliš dlouhý
    • Vyhněte se použití zpětných čar pro pokračování – používejte pouze v případě potřeby.

  • Odebrání nebo zjednodušení příkazového řádku PowerShellu (PS>) s výjimkou případů, kdy je to nutné v příkladu

  • Příklad odkazu na cmdlet musí splňovat následující schéma 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.

  • nevkládejte odstavce mezi bloky kódu. Veškerý popisný obsah musí být před bloky kódu nebo za bloky kódu.

Propojení s jinými dokumenty

  • Při propojování mimo dokumentační sadu nebo mezi referencí ke cmdletům a koncepčními informacemi.
    • Použijte adresy URL relativní vzhledem k webu pro propojení s Microsoft Learn (odeberte https://learn.microsoft.com/en-us)
    • nezahrnujte národní prostředí do adres URL ve vlastnostech Microsoftu (odeberte /en-us z adresy URL).
    • Všechny adresy URL externích webů by měly používat protokol HTTPS, pokud to není pro cílový web platné.
  • Při propojování v rámci docsetu
    • Použití relativní cesty k souboru (../folder/file.md)
  • Všechny cesty používají znaky lomítka dopředu (/).
  • Odkazy na obrázky by měly mít jedinečný alternativní text.
  • Last updated on