Megosztás a következőn keresztül:

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

A PowerShell-parancsmagok hasznosak lehetnek, de ha a súgótémakörök nem mutatják be egyértelműen a parancsmag működését és használatát, előfordulhat, hogy a parancsmag nem lesz használatban, vagy ami még rosszabb, az frusztrálhatja a felhasználókat. Az XML-alapú parancsmag súgófájlformátuma javítja a konzisztenciát, de a nagy segítséghez 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 létrehozásához szükséges XML-sémát a következő szakaszban ismertetjük. Kezdje a parancsmag súgófájljának létrehozásával. Ez a témakör a legfelső szintű XML-csomópontok leírását tartalmazza.

Útmutatók írása parancsmaghoz – súgó

Jól írható

Semmi sem helyettesíti a jól megírt témát. Ha 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 Wordbe, és a nyelvhelyességi és helyesírás-ellenőrzésekkel javítsa a munkáját.

Írás egyszerűen

Használjon egyszerű szavakat és kifejezéseket. Kerülje a zsargont. Vegye figyelembe, hogy sok olvasó csak idegen nyelvű szótárral és súgótémakörrel rendelkezik.

Következetes írás

A kapcsolódó parancsmagok súgójának hasonlónak kell lennie (például Get-Content és Set-Content). A standard paraméterek, például a Force és InputObjectszabványos leírásait használja. (Másolja őket a súgóból az alapvető parancsmagokhoz.) Használjon általános feltételeket. Használja például a "paramétert", nem az "argumentumot", és ne a "parancsmag" vagy a "command-let" parancsot.

A szinopszis indítása egy igével

A szinopszis mező tájékoztatja a felhasználót a parancsmag működéséről, nem arról, hogy mi az, és hogyan működik. Az igék létrehoznak egy feladatalapú utasítást, amely tájékoztatja a felhasználókat arról, hogy ez a parancsmag megfelel-e a követelményeknek. Használjon olyan egyszerű igéket, mint a "get", a "create" és a "change". Kerülje a "set" szót, amely lehet homályos és elegáns szavak, például a "módosítás".

Fókusz az objektumokon

A legtöbb "get" parancsmag megjelenít valamit, de elsődleges funkciója egy objektum lekérése. 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 használhatják a lekért objektum metódusait és tulajdonságait.

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

Röviden sorolja fel a parancsmag által elvégezhető összes műveletet a részletes leírásban. Ha a fő függvény egy tulajdonság módosítása, de a parancsmag az összes tulajdonságot módosíthatja, ezt a részletes leírásban találja.

Hagyományos szintaxis használata

Használja a Windows és a Unix parancssori súgójának szokásos Backus-Naur formátumát.

A Microsoft .NET-típusok használata paraméterértékekhez

A paraméterértékek helyőrzői (a szintaxisban és a paraméterleírásokban) azoknak az objektumoknak a .NET-keretrendszertípusait jelenítik meg, amelyeket a paraméter elfogad. A PowerShell csapata azért fejlesztette ki ezt a konvenciót, hogy megtanítsa a felhasználókat a .NET-keretrendszerre.

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

A paraméterleírásoknak két dologról kell tájékoztatniuk a felhasználókat: a paraméter működését (hatását) és azt, hogy mit kell beírniuk a paraméterértékekhez.

Gyakorlati példák írása

A példáknak be kell mutatniuk, hogyan kell használni az összes paramétert, de a legfontosabb az, hogy bemutassuk, hogyan kell használni a parancsmagot valós feladatokban. Kezdje egy egyszerű példával, és írjon egyre összetettebb példákat. Az utolsó példában bemutatja, hogyan használhatja a parancsmagot egy folyamatban.

A Jegyzetek mező használata

A Jegyzetek mezővel ismertetheti a parancsmag megértéséhez szükséges fogalmakat. A jegyzetek segítségével a felhasználók elkerülhetik a gyakori hibákat. Az URL-címek módosításakor kerülje az URL-címeket. Ehelyett adjon meg felhasználói kifejezéseket a kereséshez.

A súgó tesztelése

A súgó tesztelése ugyanúgy, mint a kód tesztelése. Barátai és munkatársai olvassák el a súgó tartalmát, és küldjenek visszajelzést. Visszajelzést is kérhet a hírcsoportoktól.

Lásd még:

  • Last updated on