Kontrolní seznam editoru

  • Článek

Toto je souhrn pravidel, která se mají použít při psaní nových nebo aktualizací existujících článků. Podrobné vysvětlení a příklady těchto pravidel najdete v dalších článcích příručky pro přispěvatele.

Metadata

  • 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 43–59 znaky včetně mezer
    • Nezahrnujte identifikátor lokality (vygeneruje se automaticky).
    • Použití velkých a velkých písmen ve větě – použijte pouze první slovo a jakákoli správná podstatné jméno.
  • description: 115 až 145 znaků včetně mezer – tento abstrakt se zobrazí ve výsledku hledání.

Formátování

  • Prvky syntaxe backtick, které se zobrazí v řádku v odstavci
    • Názvy rutin Verb-Noun
    • Proměnné $counter
    • Syntaktické příklady Verb-Noun -Parameter
    • Cesty k C:\Program Files\PowerShell souborům , /usr/bin/pwsh
    • Adresy URL, na které v dokumentu není možné kliknout
    • Hodnoty vlastností nebo parametrů
  • Použití tučného písma pro názvy vlastností, názvy parametrů, názvy tříd, názvy modulů, názvy entit, názvy objektů nebo typů
    • Tučné písmo se používá pro sémantické značky bez zvýraznění.
    • Tučné písmo – použijte hvězdičky **
  • Kurzíva – použití podtržítka _
    • Používá se pouze pro zvýraznění, nikoli pro sémantické značky.
  • Zalomení řádků při 100 sloupcích (nebo při 80 about_Topics)
  • Žádné pevné tabulátory – používejte pouze mezery
  • Žádné koncové mezery na řádcích
  • 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é použití správného použití kaskádových značek (Pascal).

Hlavičky

  • H1 je první – jenom jeden H1 na článek
  • Použít jenom hlavičky ATX
  • U všech záhlaví používejte velká a malá písmena věty.
  • Ne přeskočit úrovně – bez H3 bez H2
  • Maximální hloubka H3 nebo H4
  • Prázdný řádek před a po
  • PlatyPS vynucuje ve svém schématu konkrétní hlavičky – nepřidá ani neodebere hlavičky.

Bloky kódu

  • Prázdný řádek před a po
  • Použití plotů se značkou kódu – PowerShell, Výstup nebo jiné odpovídající ID jazyka
  • Neotesaný plot – bloky syntaxe nebo jiné prostředí
  • Umístěte výstup do samostatného bloku kódu s výjimkou jednoduchých příkladů, kdy nemáte v úmyslu použít tlačítko Kopírovat pro čtenáře.
  • Zobrazení seznamu podporovaných jazyků

Seznamy

  • Správné odsazení
  • Prázdný řádek před první položkou a za poslední položkou
  • Odrážka – použití spojovníku ( - ) ne hvězdičky ( * ) – příliš snadné zmást s důrazem
  • U očíslovaných seznamů jsou všechna čísla "1".

Terminologie

Příklady referenčních rutin

  • Musí obsahovat alespoň jeden příklad v referenčních rutinách.

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

  • Syntaxe PowerShellu

    • Použití úplných názvů rutin a parametrů – bez aliasů
    • Pokud je příkazový řádek příliš dlouhý, použijte pro parametry sestřídění.
    • Vyhněte se používání backticků pro pokračování řádku – používejte je jenom v případě potřeby.

  • Odeberte nebo zjednodušte příkazový řádek PowerShellu ( ), s PS> výjimkou případů, kdy je to v příkladu potřeba.

  • Referenční příklad rutiny musí dodrž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.

  • Neumisčovat odstavce mezi bloky kódu. Veškerý popisný obsah musí být před bloky kódu nebo za bloky kódu.

Odkazování na jiné dokumenty

  • Propojení mimo sadu docset nebo mezi referenčními a koncepčními rutinami
    • Při propojování s odkazem na docs.microsoft.com (odebrat ) použijte relativní adresy https://docs.microsoft.com/en-us URL.
    • Nezahrnujte národní prostředí do adres URL ve vlastnostech Microsoftu (např. odebrat /en-us z adresy URL)
    • Všechny adresy URL externích webů by měly používat protokol HTTPS, pokud nejsou platné pro cílový web.
  • V rámci sady docset
    • Odkaz na cestu k souboru (např. ../folder/file.md )
    • Všechny cesty k souborům používají znaky lomítka ( / ).
  • Odkazy na obrázky by měly mít jedinečný alternativní text