Přispívání ke zlepšení kvality

Abyste mohli přispívat, nemusíte být odborníkem na danou problematiku ani odborníkem na dokumentaci. Pokud se zobrazí příležitost ke zlepšení dokumentace, odešlete žádost o přijetí změn s navrhovaným vylepšením. Tato příručka popisuje několik jednoduchých způsobů, jak kdokoli může přispět ke zlepšení kvality v dokumentaci.

Zaměřujeme se na tyto kvalitní oblasti:

• Formátování ukázek kódu
• Syntaxe příkazu formátování
• Odkazy
• Lintování Markdownu
• Pravopis

Formátování ukázek kódu

Všechny ukázky kódu by měly dodržovat pokyny pro styl pro obsah PowerShellu. Tato pravidla se opakují ve zkrácené podobě pro usnadnění:

• Všechny bloky kódu by měly být obsaženy v trojitém zadním kódovém plotu (```).
• Délka řádku bloku kódu je omezena na 90 znaků pro referenční články o cmdletech.
• Délka řádků bloků kódu je v článcích omezena na 76 znaků.
• V příkladech kódu PowerShellu nepoužívejte znaky pokračování řádku (`).
  • Pokud chcete omezit délku řádku, používejte dělení nebo přirozené zalomení řádků, jako jsou znaky svislé čáry (|), vlnité závorky (}), kulaté závorky (() a hranaté závorky ([).
• Uveďte pouze výzvu PowerShellu k ilustrativním příkladům, kdy kód není určený pro kopírování.
• Nepoužívejte aliasy v příkladech, pokud tento alias neskumentujete konkrétně.
• Nepoužívejte poziční parametry. Použijte název parametru, i když je parametr poziční.

Syntaxe příkazu formátování

Veškerý text by měl postupovat podle pokynů pro styl pro obsah PowerShellu. Tato pravidla se opakují pro usnadnění:

• Pro cmdlety a parametry vždy používejte jejich úplné názvy. Nepoužívejte aliasy, pokud tento alias výslovně neukazujete.
• Vlastnost, parametr, objekt, názvy typů, názvy tříd, metody třídy by měly být tučné.
  • Hodnoty vlastností a parametrů by měly být uzavřeny v zpětných apostrofech (`).
  • Při odkazech na typy pomocí závorkového stylu použijte zpětné apostrofy. Příklad: [System.Io.FileInfo]
• Názvy modulů PowerShellu by měly být tučné.
• Klíčová slova a operátory PowerShellu by měly být malými písmeny.
• Pro názvy a parametry rutin použijte správné písmena (Pascal).
• Pokud odkazujete na parametr podle názvu, měl by být název tučný.
• Pokud znázorníte syntaxi, použijte název parametru se spojovníkem. Zabalte parametr do zpětných uvozovek.
• Když zobrazíte příklad použití externího příkazu, měl by být příklad zabalen do zpětných apostrofů. Vždy zahrňte příponu souboru externího příkazu.

Odkazy na odkazy

Kvůli udržovatelnosti a čitelnosti markdownových zdrojů pro naši dokumentaci převádíme koncepční dokumentaci tak, aby používala odkazové reference místo vložených odkazů.

Například místo:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Mělo by to být:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Poznámka:

Když nahradíte vložený odkaz, přeformátujte obsah tak, aby se zalomil na 100 znaků. K rychlému přeformátování odstavce můžete použít rozšíření VS Code reflow-markdown.

V dolní části souboru přidejte před definici odkazů komentář markdownu.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Ujistěte se, že:

1. Každý odkaz odkazuje na správné umístění.
2. Neduplikujte definice odkazů. Pokud již definice odkazu pro adresu URL existuje, znovu použijte existující odkaz místo vytvoření nového odkazu.
3. Definice odkazů jsou v dolní části souboru za komentářem markdownu a jsou v číselném pořadí.

Lintování Markdownu

V případě libovolného článku v jednom z zúčastněných úložišť se při otevření článku v editoru VS Code zobrazí upozornění na lintování. Vyřešte některá z těchto upozornění s výjimkou:

• MD022/blanks-around-headings/blanks-around-headers pro záhlaví Synopsis v referenčních dokumentech k rutinním příkazům PowerShell. U těchto položek je porušení pravidla úmyslné, aby byla zajištěna správná tvorba dokumentace pomocí PlatyPS.

Zkontrolujte délky řádků a použijte rozšíření Přeformátovat Markdown k opravě všech dlouhých řádků.

Pravopis

I přes naše nejlepší úsilí se překlepy a chybně napsané chyby dostanou do dokumentace a skončí v dokumentaci. Tyto chyby znesnadňuje sledování a lokalizaci dokumentace. Oprava těchto chyb zvyšuje čitelnost dokumentace, zejména pro neanglické mluvčí, kteří spoléhají na přesné překlady.