Sdílet prostřednictvím

Psaní nápovědy pro cmdlety PowerShellu

  • Článek

Rutiny PowerShellu můžou být užitečné, ale pokud vaše témata nápovědy jasně nevysvětlí, co rutina dělá a jak ji používat, nemusí se rutina používat nebo ještě horší může frustrovat uživatele. Formát souboru nápovědy nápovědy založený na jazyce XML vylepšuje konzistenci, ale skvělá nápověda vyžaduje mnohem více.

Pokud jste nikdy nenapsali nápovědu k rutině, projděte si následující pokyny. Schéma XML potřebné k vytvoření tématu nápovědy rutiny je popsáno v následující části. Začněte Vytvoření souboru nápovědy rutiny. Toto téma obsahuje popis uzlů XML nejvyšší úrovně.

Psaní pokynů pro nápovědu k rutině

Napsat dobře

Nic nenahrazuje dobře napsané téma. Pokud nejste profesionální spisovatel, vyhledejte spisovatele nebo editora, který vám pomůže. Další alternativou je zkopírování textu nápovědy do Microsoft Wordu a vylepšení práce pomocí gramatiky a kontroly pravopisu.

Jednoduše napsat

Používejte jednoduchá slova a fráze. Vyhněte se žargonu. Vezměte v úvahu, že mnoho čtenářů je vybaveno pouze slovníkem cizího jazyka a tématem nápovědy.

Zápis konzistentně

Nápověda pro související rutiny by měla být podobná (například Get-Content a Set-Content). Standardní popisy použijte pro standardní parametry, například Force a InputObject. (Zkopírujte je z nápovědy pro základní rutiny.) Používejte standardní podmínky. Například použijte parametr, nikoli argument a použijte rutinu, nikoli příkaz nebo command-let.

Zahájení synopze slovesem

Pole synopsis informuje uživatele o tom, co rutina dělá, ne co je nebo jak funguje. Příkazy vytvářejí příkaz založený na úlohách, který informuje uživatele, pokud tato rutina splňuje jejich požadavky. Používejte jednoduché příkazy, jako je get, create a change. Vyhněte se "set", což může být vágní a fancy slova jako "modify".

Zaostření na objekty

Většina rutin get něco zobrazuje, ale jejich primární funkcí je získat objekt. V nápovědě se zaměřte na objekt, aby uživatelé pochopili, že výchozí zobrazení je jedním z mnoha a že můžou používat metody a vlastnosti objektu, který jste pro ně načetli různými způsoby.

Psaní podrobných popisů

Stručně uveďte vše, co může rutina provést v podrobném popisu. Pokud je hlavní funkcí změna jedné vlastnosti, ale rutina může změnit všechny vlastnosti, uveďte ji v podrobném popisu.

Použití konvenční syntaxe

Použijte standardní formát Backus-Naur, který je běžný pro nápovědu příkazového řádku systému Windows a Unix.

Použití typů Microsoft .NET pro hodnoty parametrů

Zástupné symboly pro hodnoty parametrů (v syntaxi a popisech parametrů) zobrazují typy rozhraní .NET Framework objektů, které parametr přijme. Tým PowerShellu vyvinul tuto konvenci, aby uživatelům pomohl naučit rozhraní .NET Framework.

Zápis úplných popisů parametrů

Popisy parametrů musí uživatele informovat o dvou věcech: o tom, co parametr dělá (jeho účinek) a co musí zadat pro hodnoty parametrů.

Psaní praktických příkladů

Příklady by měly ukázat, jak používat všechny parametry, ale nejdůležitější je ukázat, jak tuto rutinu používat v reálných úkolech. Začněte jednoduchým příkladem a napište stále složitější příklady. V posledním příkladu si ukážeme, jak použít rutinu v kanálu.

Použití pole Poznámky

Pole Poznámky slouží k vysvětlení konceptů, které uživatelé potřebují k pochopení rutiny. Poznámky můžete také použít k tomu, abyste uživatelům pomohli vyhnout se běžným chybám. Vyhněte se adresám URL při změně. Místo toho zadejte termíny uživatelů, které chcete vyhledat.

Otestování nápovědy

Otestujte nápovědu stejně, jako otestujete svůj kód. Požádejte přátele a kolegy, aby si přečetli obsah nápovědy a poskytli zpětnou vazbu. Můžete také požádat o zpětnou vazbu od diskusních skupin.

Viz také