Súgócikkek írása PowerShell-parancsmagokhoz

A PowerShell-parancsmagok hasznosak lehetnek, de ha a súgótémakörei nem ismertetik egyértelműen a parancsmag funkcióját és használatát, előfordulhat, hogy a parancsmagot nem használják, vagy ami még rosszabb, frusztrációt okozhat a felhasználóknak. Az XML-alapú súgófájlformátum javítja a konzisztenciát, de a nagy segítség ennél sokkal többre van szükség.

Ha még soha nem írt súgót a parancsmaghoz, tekintse át az alábbi irányelveket. A parancsmag súgótémakörének írásához szükséges XML-sémát a következő szakasz ismerteti. Kezdje a parancsmag-súgófájl létrehozásával. Ez a témakör a legfelső szintű XML-csomópontok leírását tartalmazza.

Útmutatás írása a parancsmagokkal kapcsolatos súgóhoz

Jól megírni

Egy jól megírt témakört semmi sem helyettesít. Ha Ön nem profi író, keressen egy írót vagy szerkesztőt, aki segít Önnek. Másik lehetőségként másolja a súgószöveget a Microsoft Word és a nyelvtani és helyesírási ellenőrzésekkel javítsa a munkáját.

Írás egyszerűen

Használjon egyszerű szavakat és kifejezéseket. Kerülje a szakzsargont. Vegye figyelembe, hogy sok olvasó csak egy idegen nyelvű szótárt és az Ön súgótémakörét is fel van szerelve.

Konzisztens írás

A kapcsolódó parancsmagok súgója hasonló (például get-x és set-x). A standard paraméterek szabványos leírásait használhatja, például a Force és az InputObject paramétereket. (Másolja őket a súgóból az alapvető parancsmagok számára.) Használjon szabványos feltételeket. Például használja a "paramétert", ne az "argumentumot", és a "parancsmag" és nem a "command" vagy a "command-let" parancsot.

A szinopsis elindítani egy igével

A synopsis mező arról tájékoztatja a felhasználót, hogy mit csinál a parancsmag, nem pedig azt, hogy mi az, vagy hogyan működik. A műveletek feladatalapú utasítást hoznak létre, amely tájékoztatja a felhasználókat, ha ez a parancsmag megfelel a követelményeknek. Használjon olyan egyszerű műveleteket, mint a "get", a "create" és a "change". Kerülje a "set" (beállítás) halmazt, amely egyértelmű és elegáns szavak, például "módosítás" lehet.

Fókusz az objektumokon

A legtöbb "get" parancsmag megjelenít valamit, de elsődleges funkciójuk egy objektum leválasztása. A Súgóban koncentráljon az objektumra, hogy a felhasználók megértsék, hogy az alapértelmezett megjelenítés a sok közül az egyik, és hogy különböző módokon tudják használni a lekért objektum metódusát és tulajdonságait.

Részletes leírások írása

Röviden soroljon fel mindent, amire a parancsmag a részletes leírásban képes. Ha a fő függvény egy tulajdonság módosítása, de a parancsmag az összes tulajdonságot módosíthatja, sorolja fel ezt a részletes leírásban.

Hagyományos szintaxis használata

Használja a szabványos Backus-Naur formátumot, amely gyakori Windows és UNIX parancssori súgóban.

Paraméterértékek Microsoft .NET típusokkal

A paraméterértékek helyőrzői (a szintaxisban és a paraméterek leírásában) a .NET-keretrendszer által elfogadt objektumok típusát mutatják. A PowerShell csapata kifejlesztette ezt a konvenciót, amely segít megtanítani a felhasználókat a .NET-keretrendszer.

Teljes paraméterleírások írása

A paraméterek leírásának két dologról kell tájékoztatnia a felhasználókat: mit csinál a paraméter (milyen hatással van), és mit kell begépelnie a paraméterértékek számára.

Gyakorlati példák írása

A példák bemutatják, hogyan használhatja az összes paramétert, de a legfontosabb, hogy bemutatja, hogyan használhatja a parancsmagot a valós feladatokban. Kezdjen egy egyszerű példával, és írjon egyre összetettebb példákat. Az utolsó példában a parancsmag folyamatokban való használatát mutatjuk be.

A Megjegyzések mező használata

A Megjegyzések mezőben ismertetheti, hogy a felhasználóknak milyen fogalmakat kell megérteniük a parancsmaghoz. Megjegyzéseket is használhat, hogy segítsen a felhasználóknak elkerülni a gyakori hibákat. Kerülje az URL-címeket a módosításuk közben. Ehelyett adja meg a keresett kifejezéseket a felhasználók számára.

A súgó tesztelése

Tesztelje a súgót, ahogy a kódot is teszteli. Barátaival és munkatársaival olvassa el súgótartalmakat, és adjanak visszajelzést. Visszajelzést is küldhet a hírcsoportoktól.

Lásd még:

Parancsmag súgófájljának létrehozása

Parancsmag nevének és összefoglalójának hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Részletes leírás hozzáadása egy parancsmagokkal kapcsolatos súgótémakörbe

Szintaxis hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Paraméterek hozzáadása parancsmagokkal kapcsolatos súgótémakörbe

Bemeneti típusok hozzáadása egy parancsmagokkal kapcsolatos súgótémakörbe

Visszatérési értékek hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Jegyzetek hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Példák hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Kapcsolódó hivatkozások hozzáadása egy parancsmagokkal kapcsolatos súgótémakörhöz

Windows PowerShell SDK