Pisanie pomocy dla poleceń cmdlet programu PowerShellWriting Help for PowerShell Cmdlets

Polecenia cmdlet programu PowerShell mogą być przydatne, ale jeśli w innych tematach pomocy nie wyjaśniono, jak działa polecenie cmdlet i jak z niego korzystać, polecenie cmdlet może nie zostać użyte lub nawet gorsze, może frustrować użytkowników.PowerShell cmdlets can be useful, but unless your Help topics clearly explain what the cmdlet does and how to use it, the cmdlet may not get used or, even worse, it might frustrate users. Plik pomocy poleceń cmdlet opartych na języku XML zwiększa spójność, ale świetna pomoc wymaga dużo więcej.The XML-based cmdlet Help file format enhances consistency, but great help requires much more.

Jeśli nigdy nie zapisano pomocy polecenia cmdlet, zapoznaj się z poniższymi wskazówkami.If you have never written cmdlet Help, review the following guidelines. Schemat XML wymagany do utworzenia tematu pomocy polecenia cmdlet został opisany w następnej sekcji.The XML schema required to author the cmdlet Help topic is described in the following section. Zacznij od utworzenia pliku pomocy poleceń cmdlet.Start with Creating the Cmdlet Help File. Ten temat zawiera opis węzłów XML najwyższego poziomu.That topic includes a description of the top-level XML nodes.

Pisanie wytycznych dotyczących pomocy dotyczącej poleceń cmdletWriting Guidelines for Cmdlet Help

Źródło zapisuWrite well

Nic nie zastępuje dobrze zarejestrowanego tematu.Nothing replaces a well-written topic. Jeśli nie jesteś autorem profesjonalnych, Znajdź składnik zapisywania lub Edytor, który pomoże Ci.If you are not a professional writer, find a writer or editor to help you. Kolejną alternatywą jest skopiowanie tekstu pomocy do programu Microsoft Word i przetestowanie pracy przy użyciu gramatyki i sprawdzania pisowni.Another alternative is to copy your Help text into Microsoft Word and use the grammar and spelling checks to improve your work.

Napisz po prostuWrite simply

Używaj prostych słów i fraz.Use simple words and phrases. Należy unikać żargon.Avoid jargon. Należy wziąć pod uwagę, że wielu czytników jest wyposażonych tylko w słowniku obcym i w temacie pomocy.Consider that many readers are equipped only with a foreign-language dictionary and your Help topic.

Spójny zapisWrite consistently

Pomoc dotycząca powiązanych poleceń cmdlet powinna być podobna (na przykład Get-x i Set-x).Help for related cmdlets should be similar (for example, get-x and set-x). Użyj standardowych opisów parametrów standardowych, takich jak Force i inputobject.Use the standard descriptions for standard parameters, like Force and InputObject. (Skopiuj je z pomocy dotyczącej podstawowych poleceń cmdlet). Użyj standardowych warunków.(Copy them from Help for the core cmdlets.) Use standard terms. Na przykład użyj "parameter", nie "argument" i Użyj "cmdlet" nie "Command" lub "Command-let".For example, use "parameter", not "argument", and use "cmdlet" not "command" or "command-let."

Rozpocznij streszczenie przy użyciu zleceniaStart the synopsis with a verb

Pole streszczenie zawiera informacje o tym, co robi polecenie cmdlet, a nie jego działania lub jak działa.The synopsis field informs the user what the cmdlet does, not what it is or how it works. Czasowniki tworzą instrukcję opartą na zadaniach, która informuje użytkowników, jeśli to polecenie cmdlet spełnia ich wymagania.Verbs create a task-based statement that informs users if this cmdlet meets their requirements. Użyj prostych zleceń, takich jak "Get", "Create" i "Change".Use simple verbs like "get", "create", and "change." Należy unikać "Set", które mogą być niejasne i ozdobne słowa, takie jak "Modify".Avoid "set", which can be vague and fancy words like "modify".

Koncentrowanie się na obiektachFocus on objects

Większość poleceń cmdlet "Get" wyświetla coś, ale ich podstawową funkcją jest uzyskanie obiektu.Most "get" cmdlets display something, but their primary function is to get an object. W Twojej pomocy należy skoncentrować się na obiekcie, aby użytkownicy rozumieli, że domyślny ekran jest jednym z wielu i że mogą używać metod i właściwości obiektu, który został pobrany dla nich na różne sposoby.In your Help, focus on the object, so that users understand that the default display is one of many, and that they can use the methods and properties of the object that you retrieved for them in different ways.

Napisz szczegółowe opisyWrite detailed descriptions

Zwięźle pokrótce listę wszystkich elementów, które może wykonać polecenie cmdlet w szczegółowym opisie.Briefly list everything that the cmdlet can do in the detailed description. Jeśli główną funkcją jest zmiana jednej właściwości, ale polecenie cmdlet może zmienić wszystkie właściwości, Wyświetl je w szczegółowym opisie.If the main function is to change one property, but the cmdlet can change all properties, list this in the detailed description.

Użyj konwencjonalnej składniUse conventional syntax

Użyj standardowego formatu back-Naura, który jest typowy dla pomocy wiersza polecenia systemu Windows i UNIX.Use the standard Backus-Naur format which is common for Windows and UNIX command-line Help.

Użyj typów Microsoft .NET dla wartości parametrówUse Microsoft .NET types for parameter values

Symbole zastępcze dla wartości parametrów (w opisach składni i parametrów) pokazują .NET Framework typy obiektów, które zostaną zaakceptowane przez parametr.The placeholders for parameter values (in the syntax and parameter descriptions) show the .NET Framework types of the objects that the parameter will accept. Zespół programu PowerShell opracował tę Konwencję, aby pomóc użytkownikom w nauce .NET Framework.The PowerShell team developed this convention to help teach users about the .NET Framework.

Zapisz kompletne opisy parametrówWrite complete parameter descriptions

Opisy parametrów muszą informować użytkowników o dwóch kwestiach: jaki parametr (jego efekt) i co należy wpisać dla wartości parametrów.Parameter descriptions must inform users of two things: what the parameter does (its effect) and what they must type for the parameter values.

Napisz Przykłady praktyczneWrite practical examples

W przykładach powinna być wyświetlana informacja, jak używać wszystkich parametrów, ale najważniejsze jest, aby pokazać, jak używać polecenia cmdlet w rzeczywistych zadaniach.The examples should show how to use all of the parameters, but the most important thing is to show how to use the cmdlet in real-world tasks. Zacznij od prostego przykładu i napisz coraz bardziej złożone przykłady.Start with a simple example and write increasingly complex examples. W ostatnim przykładzie pokazano, jak używać polecenia cmdlet w potoku.In the final example, show how to use the cmdlet in a pipeline.

Używanie pola uwagiUse the Notes field

Użyj pola uwagi, aby wyjaśnić koncepcje, które użytkownicy muszą zrozumieć polecenie cmdlet.Use the Notes field to explain concepts that users need to understand the cmdlet. Możesz również użyć notatek, aby ułatwić użytkownikom uniknięcie typowych błędów.You can also use notes to help users avoid common errors. Należy unikać adresów URL w miarę ich zmiany.Avoid URLs as they change. Zamiast tego Podaj warunki dla użytkowników, które mają być wyszukiwane.Instead, provide users terms to search for.

Testowanie pomocyTest your Help

Przetestuj pomoc, tak jak w przypadku testowania kodu.Test the Help just like you test your code. Skontaktuj się z przyjaciółmi i współpracownikami, aby przeczytać zawartość pomocy i przekazać opinię.Have friends and colleagues read your Help content and provide feedback. Możesz również zażądanie opinii z grup dyskusyjnych.You can also solicit feedback from newsgroups.

Zobacz teżSee Also

Jak utworzyć plik pomocy dotyczącej poleceń cmdletHow to Create the Cmdlet Help File

Jak dodać nazwę polecenia cmdlet i streszczenie do tematu pomocy dotyczącego polecenia cmdletHow to Add the Cmdlet Name and Synopsis to a Cmdlet Help Topic

Jak dodać szczegółowy opis do tematu pomocy polecenia cmdletHow to Add the Detailed Description to a Cmdlet Help Topic

Jak dodać składnię do tematu pomocy dotyczącego polecenia cmdletHow to Add Syntax to a Cmdlet Help Topic

Jak dodać parametry do tematu pomocy polecenia cmdletHow to Add Parameters to a Cmdlet Help Topic

Jak dodać typy wejściowe do tematu pomocy polecenia cmdletHow to add Input Types to a Cmdlet Help Topic

Jak dodać wartości zwracane do tematu pomocy dotyczącego polecenia cmdletHow to Add Return Values to a Cmdlet Help Topic

Jak dodać notatki do tematu pomocy dotyczącego polecenia cmdletHow to Add Notes to a Cmdlet Help Topic

Jak dodać przykłady do tematu pomocy dotyczącego polecenia cmdletHow to Add Examples to a Cmdlet Help Topic

Jak dodać powiązane linki do tematu pomocy dotyczącego polecenia cmdletHow to Add Related Links to a Cmdlet Help Topic

Windows PowerShell SDKWindows PowerShell SDK