Súgócikkek írása PowerShell-parancsmagokhozWriting Help for PowerShell Cmdlets

A PowerShell-parancsmagok hasznosak lehetnek, de ha a súgó témakörei nem magyarázzák el világosan a parancsmag használatát és használatának módját, akkor előfordulhat, hogy a parancsmag nem lesz felhasználva, vagy még rosszabb, hogy a felhasználók meghiúsítják a felhasználókat.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. Az XML-alapú parancsmag Súgó fájlformátuma javítja a konzisztenciát, de a nagy segítség sokkal többre van szükség.The XML-based cmdlet Help file format enhances consistency, but great help requires much more.

Ha még soha nem írt parancsmag súgóját, tekintse át a következő irányelveket.If you have never written cmdlet Help, review the following guidelines. A parancsmag súgójának létrehozásához szükséges XML-sémát a következő szakasz ismerteti.The XML schema required to author the cmdlet Help topic is described in the following section. Kezdje a parancsmag súgófájl létrehozásával.Start with Creating the Cmdlet Help File. Ez a témakör a legfelső szintű XML-csomópontok leírását tartalmazza.That topic includes a description of the top-level XML nodes.

Útmutató a parancsmag súgójának írásáhozWriting Guidelines for Cmdlet Help

Írás jólWrite well

Semmi nem helyettesíti a jól megírt témakört.Nothing replaces a well-written topic. Ha nem hivatásos író, keressen egy író vagy szerkesztő segítségét.If you are not a professional writer, find a writer or editor to help you. Egy másik alternatíva a Súgó szövegének másolása a Microsoft Wordbe, és a nyelvtani és helyesírási ellenőrzések használatával javíthatja a munkáját.Another alternative is to copy your Help text into Microsoft Word and use the grammar and spelling checks to improve your work.

Egyszerűen írhatóWrite simply

Használjon egyszerű szavakat és kifejezéseket.Use simple words and phrases. Kerülje a zsargont.Avoid jargon. Vegye figyelembe, hogy számos olvasó csak idegen nyelvű szótárral és a súgótémakörre van ellátva.Consider that many readers are equipped only with a foreign-language dictionary and your Help topic.

Konzisztens írásWrite consistently

A kapcsolódó parancsmagok súgójának hasonlónak kell lennie (például Get-x és set-x).Help for related cmdlets should be similar (for example, get-x and set-x). Használja a szabványos paraméterek szabványos leírását, például a Force és a inputobject elemnél .Use the standard descriptions for standard parameters, like Force and InputObject . (Másolja őket a súgóból a Core parancsmagokhoz.) Szabványos kifejezések használata.(Copy them from Help for the core cmdlets.) Use standard terms. Használja például a "paraméter", nem "argumentum" kifejezést, és használja a "parancsmag" nem "Command" vagy "Command-let" parancsot.For example, use "parameter", not "argument", and use "cmdlet" not "command" or "command-let."

Az Áttekintés elindítása egy művelettelStart the synopsis with a verb

Az Áttekintés mező tájékoztatja a felhasználót, hogy mi a parancsmag, és nem az, hogy mi ez, vagy hogyan működik.The synopsis field informs the user what the cmdlet does, not what it is or how it works. A műveletek olyan feladatütemezés-alapú utasítást hoznak létre, amely tájékoztatja a felhasználókat, ha a parancsmag megfelel a követelményeiknek.Verbs create a task-based statement that informs users if this cmdlet meets their requirements. Használjon olyan egyszerű műveleteket, mint a "Get", a "Create" és a "Change".Use simple verbs like "get", "create", and "change." Kerülje a "Set" kifejezést, amely lehet homályos és képzeletbeli szavak, például "módosítás".Avoid "set", which can be vague and fancy words like "modify".

Fókuszban lévő objektumokFocus on objects

A legtöbb "Get" parancsmag megjelenít valamit, de elsődleges funkciója egy objektum lekérése.Most "get" cmdlets display something, but their primary function is to get an object. A súgóban összpontosítson az objektumra, hogy a felhasználók tisztában legyenek azzal, hogy az alapértelmezett megjelenítés az egyik a sok közül, és hogy a különböző módokon beolvasott objektum metódusait és tulajdonságait használják.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.

Részletes leírások írásaWrite detailed descriptions

Röviden listázhatja a parancsmag által a részletes leírásban megtehető mindent.Briefly list everything that the cmdlet can do in the detailed description. Ha a fő függvény egy tulajdonság módosítása, de a parancsmag az összes tulajdonságot megváltoztathatja, a részletes leírásban megadhatja ezt.If the main function is to change one property, but the cmdlet can change all properties, list this in the detailed description.

Hagyományos szintaxis használataUse conventional syntax

Használja a szabványos Backus-Naur formátumot, amely a Windows és a UNIX parancssori súgójában gyakori.Use the standard Backus-Naur format which is common for Windows and UNIX command-line Help.

A paraméterek értékeinek Microsoft .NET típusának használataUse Microsoft .NET types for parameter values

A paraméterek értékeinek helyőrzői (a szintaxis és a paraméterek leírásában) megjelenítik azon objektumok .NET-keretrendszerének típusait, amelyeket a paraméter el fog fogadni.The placeholders for parameter values (in the syntax and parameter descriptions) show the .NET Framework types of the objects that the parameter will accept. A PowerShell-csapat fejlesztette ezt az egyezményt, hogy segítsen a felhasználóknak a .NET-keretrendszerrel kapcsolatos tanításában.The PowerShell team developed this convention to help teach users about the .NET Framework.

Írási teljes paraméter leírásaWrite complete parameter descriptions

A paraméterek leírásának két dologból kell tájékoztatnia a felhasználókat: a paramétert (annak hatását), valamint azt, hogy mit kell megadniuk a paraméterek értékeinek.Parameter descriptions must inform users of two things: what the parameter does (its effect) and what they must type for the parameter values.

Praktikus példák írásaWrite practical examples

A példáknak meg kell mutatniuk, hogyan használhatók az összes paraméter, de a legfontosabb dolog a parancsmag használata a valós feladatokban.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. Kezdje egy egyszerű példával, és írjon egyre összetettebb példákat.Start with a simple example and write increasingly complex examples. Az utolsó példában megmutatjuk, hogyan használhatja a parancsmagot egy folyamaton belül.In the final example, show how to use the cmdlet in a pipeline.

A megjegyzések mező használataUse the Notes field

A megjegyzések mező segítségével ismertesse azokat a fogalmakat, amelyeknek a felhasználóknak ismerniük kell a parancsmagot.Use the Notes field to explain concepts that users need to understand the cmdlet. A megjegyzések segítségével a felhasználók elkerülhetik a gyakori hibákat.You can also use notes to help users avoid common errors. Ne módosítsa az URL-címeket.Avoid URLs as they change. Ehelyett adja meg a felhasználóknak a keresendő kifejezéseket.Instead, provide users terms to search for.

A Súgó teszteléseTest your Help

Tesztelje a súgót ugyanúgy, mint a kód teszteléséhez.Test the Help just like you test your code. Barátokkal és munkatársakkal olvassa el a súgó tartalmát, és küldjön visszajelzést.Have friends and colleagues read your Help content and provide feedback. A hírcsoportokból is kérhet visszajelzést.You can also solicit feedback from newsgroups.

Lásd még:See Also

Parancsmag súgófájljának létrehozásaHow to Create the Cmdlet Help File

Parancsmag nevének és összefoglalójának hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add the Cmdlet Name and Synopsis to a Cmdlet Help Topic

A részletes leírás hozzáadása egy parancsmag Súgó témakörhözHow to Add the Detailed Description to a Cmdlet Help Topic

Szintaxis hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Syntax to a Cmdlet Help Topic

Paraméterek hozzáadása a parancsmagok Súgó témaköréhezHow to Add Parameters to a Cmdlet Help Topic

Bemeneti típusok hozzáadása egy parancsmag Súgó témakörhözHow to add Input Types to a Cmdlet Help Topic

Visszatérési értékek hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Return Values to a Cmdlet Help Topic

Jegyzetek hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Notes to a Cmdlet Help Topic

Példák hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Examples to a Cmdlet Help Topic

Kapcsolódó hivatkozások hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhözHow to Add Related Links to a Cmdlet Help Topic

Windows PowerShell SDKWindows PowerShell SDK