A jó szoftverdokumentáció, legyen az specifikációs dokumentáció a programozók és tesztelők számára, műszaki dokumentumok a belső felhasználók számára, vagy kézikönyvek és súgófájlok a végfelhasználók számára, segít a felhasználóknak megérteni a szoftver jellemzőit és funkcióit. A jó dokumentáció olyan dokumentáció, amely specifikus, világos és releváns, a felhasználó számára szükséges összes információval. Ez a cikk útmutatást nyújt a műszaki dokumentáció írásához a műszaki felhasználók és a végfelhasználók számára.
Lépés
1. módszer 2 -ből: Szoftverdokumentáció írása műszaki felhasználók számára
1. lépés. Tudja, hogy milyen információkat kell tartalmaznia
A specifikációs dokumentum referencia kézikönyvként szolgál interfész tervezők, kódot író programozók és a szoftver teljesítményét ellenőrző tesztelők számára. A szükséges adatok a létrehozandó programtól függenek, de a következőket tartalmazhatják:
- Fontos fájlok az alkalmazásban, például a fejlesztői csapat által létrehozott fájlok, a program futása közben hozzáférhető adatbázisok és harmadik féltől származó alkalmazások.
- Funkciók és alprogramok, beleértve a függvény/alprogram használatának magyarázatát, a bemeneti és kimeneti értékeket.
- Programváltozók és állandók, valamint azok használata.
- A program általános felépítése. A meghajtóalapú programoknál szükség lehet az egyes modulok és könyvtárak leírására. Vagy ha kézikönyvet ír egy webes programhoz, akkor el kell magyaráznia, hogy az egyes oldalak mely fájlokat használják.
2. lépés Döntse el, hogy milyen szintű dokumentációnak kell jelen lennie és elválasztható a programkódtól
Minél több műszaki dokumentációt tartalmaz a programkód, annál könnyebb lesz frissíteni és karbantartani, valamint elmagyarázni a program különböző verzióit. A programkód dokumentációjának legalább tartalmaznia kell a függvények, alprogramok, változók és állandók használatát.
- Ha a forráskód hosszú, dokumentációt írhat egy súgófájlba, amelyet ezután indexelhet vagy kereshet bizonyos kulcsszavakkal. Külön dokumentációs fájlok akkor hasznosak, ha a programlogika több oldalra van felosztva, és támogatási fájlokat tartalmaz, például egy webalkalmazást.
- Néhány programozási nyelv (például Java, Visual Basic. NET vagy C#) saját kóddokumentációs szabványokkal rendelkezik. Ilyen esetekben kövesse a szabványos dokumentációt, amelyet a forráskódnak tartalmaznia kell.
3. lépés Válassza ki a megfelelő dokumentációs eszközt
Bizonyos esetekben a dokumentációs eszközt a használt programozási nyelv határozza meg. A C ++, C#, Visual Basic, Java, PHP és más nyelveknek saját dokumentációs eszközeik vannak. Ha azonban nem, akkor az alkalmazott eszközök a szükséges dokumentációtól függenek.
- A szövegszerkesztő, például a Microsoft Word alkalmas dokumentumszöveg -fájlok létrehozására, amennyiben a dokumentáció tömör és egyszerű. Ahhoz, hogy hosszú dokumentációt készítsen összetett szöveggel, a legtöbb műszaki író speciális dokumentációs eszközt választ, például az Adobe FrameMaker -t.
- A forráskód dokumentálására szolgáló súgófájlok létrehozhatók egy támogató fájlgeneráló programmal, mint például a RoboHelp, a Help and Manual, a Doc-To-Help, a MadCap Flare vagy a HelpLogix.
2. módszer 2 -ből: Szoftverdokumentáció írása a végfelhasználók számára
1. lépés Ismerje meg a kézikönyv létrehozásának üzleti okait
Bár a szoftverdokumentáció fő oka az, hogy segítsen a felhasználóknak megérteni az alkalmazás használatát, számos más ok is állhat a dokumentáció létrehozásának hátterében, például a marketing részleg segítése az alkalmazás eladásában, a vállalat imázsának javítása és a technikai támogatás csökkentése költségeket. Bizonyos esetekben dokumentációra van szükség ahhoz, hogy megfeleljen az előírásoknak vagy más jogi követelményeknek.
A dokumentáció azonban nem helyettesíti az interfészt. Ha egy alkalmazás működéséhez sok dokumentációra van szükség, akkor intuitívabbnak kell lennie
2. lépés Ismerje a dokumentáció célközönségét
A szoftverhasználók általában korlátozott számítógépes ismeretekkel rendelkeznek az általuk használt alkalmazásokon túl. Számos módja van a dokumentációs igények kielégítésére:
- Ügyeljen a szoftver felhasználó címére. Például a rendszergazda általában megérti a különböző számítógépes alkalmazásokat, míg a titkár csak azokat az alkalmazásokat ismeri, amelyeket az adatok bevitelére használ.
- Ügyeljen a szoftverhasználókra. Bár beosztásuk általában összeegyeztethető az elvégzett feladatokkal, ezek a pozíciók eltérő terheléssel rendelkezhetnek, az üzleti helytől függően. A potenciális felhasználókat megkérdezve megtudhatja, hogy a munkakörük megítélése helyes -e.
- Ügyeljen a meglévő dokumentációra. A szoftver működési dokumentációja és specifikációi megmutathatják, hogy a felhasználóknak mit kell tudniuk a használathoz. Ne feledje azonban, hogy előfordulhat, hogy a felhasználókat nem érdekli a program "belsejének" ismerete.
- Tudja meg, mi szükséges egy feladat elvégzéséhez, és mi szükséges ahhoz, hogy befejezze.
3. lépés. Határozza meg a dokumentáció megfelelő formátumát
A szoftverdokumentáció 1 vagy 2 formátumban, nevezetesen kézikönyvekben és kézikönyvekben rendezhető. Néha a két formátum kombinálása jó megoldás.
- A referenciaformátumok leírják az összes szoftverfunkciót, például a gombokat, füleket, mezőket és párbeszédpaneleket, valamint azok működését. Néhány súgófájl ebben a formátumban íródott, különösen azok, amelyek környezetfüggők. Amikor a felhasználó a Súgó gombra kattint egy bizonyos képernyőn, a felhasználó megkapja a megfelelő témát.
- A kézi formátum magyarázza el, hogyan kell valamit csinálni a szoftverrel. A kézikönyvek általában nyomtatott vagy PDF formátumban készülnek, bár néhány súgóoldal bizonyos utasításokat is tartalmaz. (Általában a kézi formátumok nem kontextus -érzékenyek, de kapcsolódhatnak a környezetfüggő témákhoz). A kézikönyvek általában útmutató formájában készülnek, leírásban az elvégzendő feladatok összegzésével és lépésben formázott útmutatóval.
4. lépés Döntse el a dokumentáció típusát
A felhasználóknak szánt szoftverdokumentáció az alábbi formátumok egy vagy több csomagolásába csomagolható: nyomtatott kézikönyvek, PDF -fájlok, súgófájlok vagy online súgó. Mindegyik dokumentációtípus bemutatja a szoftver funkcióinak használatát, legyen az útmutató vagy oktatóanyag. Az online dokumentáció és súgóoldal bemutató videókat, szöveget és statikus képeket is tartalmazhat.
Az online súgó- és támogatási fájlokat indexelni és keresni kell kulcsszavak használatával, hogy a felhasználók gyorsan megtalálják a szükséges információkat. Bár a súgófájl -generáló alkalmazás képes automatikusan indexet létrehozni, továbbra is ajánlott manuálisan létrehozni egy indexet az általánosan keresett kulcsszavak használatával
5. lépés Válassza ki a megfelelő dokumentációs eszközt
A fájlok hosszától és összetettségétől függően nyomtatott kézikönyvek vagy PDF -ek létrehozhatók egy szövegszerkesztő programmal, például a Word -szel vagy egy speciális szövegszerkesztővel, például a FrameMakerrel. A súgófájlok írhatók egy súgófájl-készítő programmal, például RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix vagy HelpServer.
Tippek
- A programdokumentáció szövegét úgy kell felépíteni, hogy könnyen olvasható legyen. Helyezze a képet a lehető legközelebb a megfelelő szöveghez. Logikusan bontja le a dokumentációt szakaszok és témák szerint. Minden szakasznak vagy témakörnek egy konkrét problémát kell leírnia, mind a feladatokat, mind a program jellemzőit. A kapcsolódó problémák linkekkel vagy hivatkozási listákkal magyarázhatók.
- A cikkben ismertetett dokumentációs eszközök mindegyikét kiegészítheti egy képernyőkép készítő program, például a SnagIt, ha a dokumentáció több képernyőképet igényel. Mint minden más dokumentációhoz, mellékeljen képernyőképeket is, amelyek segítenek elmagyarázni az alkalmazás működését, ahelyett, hogy "elcsábítanák" a felhasználót.
- A stílusra való odafigyelés nagyon fontos, különösen akkor, ha szoftverdokumentációt ír a végfelhasználóknak. A "felhasználó" helyett "te" névmással címezheti a felhasználókat.
