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
Visszajelzés
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Visszajelzés küldése és megtekintése a következőhöz: