A szoftver dokumentációjának írása: 8 lépés

Jó szoftverdokumentáció - A programozóknak vagy tesztelőknek a programozók vagy tesztelőkre vonatkozó követelmények, a belső felhasználók műszaki dokumentációja, a szoftverek használata vagy a felhasználók programjainak kézikönyvének kézikönyve - segít a szoftverrel dolgozó személynek, megértse a szoftverrel dolgozó személyt, megértse a jellemző tulajdonságait és funkciók. Kövesse a tippeket - Hogyan írjon szoftver dokumentációt a technikai és végfelhasználók számára.

Lépések

1. módszer: 2:

Szoftverek dokumentációja műszaki felhasználók számára.

egy. Meghatározza, hogy mely információkat kell megemlíteni. A szoftverkövetelményekre vonatkozó dokumentumok referencia kézikönyvként szolgálnak a felhasználói felület tervezők, programozók, akik kódot és tesztelőket írnak, amelyek ellenőrzik, hogy a szoftver az alábbiak szerint működik-e. A pontos információ a programtól függ, azonban a következőket tartalmazhatja:

Kulcsfájlok az alkalmazásban. Ezek lehetnek a fejlesztői csapat által létrehozott fájlok, a szoftver működés során okozott adatbázisok és a harmadik fél szolgáltatási programjai.
Funkciók és szubrutinok. Itt van, hogy minden funkció és szubrutin teszi, beleértve a bemeneti és kimeneti értékeket.
Szoftverváltozók és konstans és hogyan használják őket az alkalmazásban.
A program általános felépítése. A lemezalapú alkalmazásokhoz valószínűleg szükség van az egyes blokkok és a programkönyvtárak leírására, míg a webes alkalmazásoknak fájlokat igényelnek, amelyek fájlokat használnak.

A kép Write Software Dokumentáció 2. lépés

2. Döntse el, hogy hány dokumentációt kell a programkódban, és mennyit kell elválasztani. Minél többet hoz létre a műszaki dokumentáció a programkódban, annál könnyebb frissíteni ezt a kódot az eredeti alkalmazás különböző verzióira vonatkozó dokumentációként. Legalább a programkód dokumentációjának meg kell magyaráznia a funkciókat, szubrutinokat, szoftverállállókat és változókat.

Ha a programkód meglehetősen hosszú, akkor referenciafájlként lehet elhelyezni, amelyben kulcsszavakkal vagy jelzőtáblákkal kereshet. Ez nagy plusz lesz olyan alkalmazásokhoz, ahol a program logikája sok oldalra oszlik, és tartalmaz egy segédfájlszámokat, mint bizonyos webes alkalmazásokban.

Néhány programozási nyelv, például Java vagy Net Framework (Visual Basic.Net, C #) saját szabványaik a dokumentációs kódhoz. Ilyen esetekben kövesse a szabványos utasításokat - hány dokumentációt kell tartalmaznia a programkódba.

A kép írása Szoftver dokumentáció 3. lépés

3. Válasszon megfelelő eszközt. Bizonyos mértékig ezt a kódot a kód írásban határozzák meg, legyen C ++, C #, Visual Basic, Java vagy PHP - mindenkinek van saját eszközünk. Más esetekben az alkalmazott szerszámot a szükséges dokumentáció típusa határozza meg.

Szövegszerkesztő "Microsoft Word" -Cercing eszköz különálló szöveges fájlok dokumentációjának létrehozásához, amely egyszerű és rövid lesz. Hosszú szöveges fájlok esetén számos műszaki dokumentáció fejlesztő szeretne kiválasztani az Adobe Framemaker programot.

A szoftverkód dokumentációjának csúcsfájlja bármely eszközzel, például Robbohelp, Súgó és Kézi, Doc-to Súgó, Madcap Flare vagy "Helplogix" használatával írható.

2. módszer 2:

Szoftverdokumentáció írása a végfelhasználók számára

egy. Határozza meg a dokumentáció kereskedelmi megfontolását. Bár a szoftverdokumentáció funkcionális okai segítenek abban, hogy segítsenek a felhasználóknak megérteni, hogyan kell használni az alkalmazást, vannak olyan okok, amelyek segítenek a piacon lévő áruk előmozdításában, javítva a vállalat képét és a legfontosabb dolgot, csökkentve a technikai támogatási költségek csökkentését. Bizonyos esetekben a dokumentációnak meg kell felelnie bizonyos szabályoknak és jogi követelményeknek.

A programdokumentáció semmilyen esetben sem helyettesítheti a rossz felület kialakítását. Ha az alkalmazás képernyője sok magyarázó dokumentációt igényel, akkor jobb, ha valami intuitívabbá válik.

A kép írása Szoftver dokumentáció 5. lépés

2. Értsd meg a közönséget, amelyre dokumentációt írsz. A legtöbb esetben a szoftverhasználók kevésbé ismerik a számítógépeket az alkalmazási feladatok mellett. Számos módja van annak meghatározására, hogyan koordinálja szükségleteiket a dokumentációval.

Nézd meg a potenciális felhasználók tulajdonában lévő szakmákat. A rendszergazda valószínűleg szakértője lesz a szoftveralkalmazások használatával, míg az adatbeviteli szolgáltató valószínűleg saját alkalmazást használ, hogy az adatbevitelhez használja.

Nézd meg maguk a felhasználókat. Bár helyükön általában meghatározzák, milyen emberek vesznek részt, de vannak jelentős különbségek, hogy bizonyos pozíciókban használják a szervezeten belül. A potenciális felhasználókkal való interjú lefolytatása, hozzáadhatja véleményét - teljesíti a hozzászólás nevét a feladatokat.

Lásd a meglévő dokumentációt. A korábbi szoftver verziók dokumentációja hozzávetőleges koncepciót ad, hogy a felhasználónak tudnia kell a program használatáról. Ne feledje azonban, hogy a végfelhasználók nem érdekli, hogyan működik a program, fontos számukra, hogy tudják, mit tehetnek vele.

Határozza meg az ehhez a munkához szükséges feladatokat, és milyen feladatokat kell elvégezni, mielőtt ezeket a feladatokat elvégeznének.

A kép Write szoftver dokumentáció 6. lépés

3. Határozza meg a dokumentáció megfelelő formátumát. A szoftver dokumentációja a két formátumban - a referencia-útmutató és a használati utasítások között lehet felépíteni. Néha jobb választani a két formátum vegyes verzióját.

A referencia-útmutató úgy van kialakítva, hogy megmagyarázza a szoftver eszközeit (gombok, táblázatok, mező és párbeszédpanel), és hogyan működik ez az eszközkit. Számos gyorsfájl van jelen ebben a formátumban, és a kontextus utasításai segítenek a kívánt téma megjelenítéséhez, miután a felhasználó a kívánt képernyőn megjelenő "Súgó" gombra kattint.

A Használati utasítások megmagyarázzák, hogyan kell használni a szoftvert egy adott feladat elvégzéséhez. A használati utasítás gyakran nyomtatott útmutatóval vagy PDF formátummal rendelkezik, bár egyes utasítások tartalmazzák a konkrét feladat végrehajtásának témáit. (Ezek a referencia témák általában nem kontextusok, bár hiperhivatkozások lehetnek) A használati utasítás gyakran referenciakönyv formájában van egy feladatleírással és lépésenkénti utasításokkal.

A kép írása Szoftver dokumentáció 7. lépés

4. Döntse el, hogy melyik formátum (formátumok) kell lennie. A végfelhasználók szoftverdokumentációja lehet egy vagy több formátum: nyomtatási útmutató, dokumentumok PDF formátumban, tippfájlok vagy online súgó. Mindegyik formátum létrejön, hogy megmutassa a felhasználót, hogyan kell használni az egyes programfunkciókat - legyen egy rövid áttekintés vagy útmutató. Mint a gyors fájlok és az online súgó esetében, a dokumentációnak demonstrációs videója vagy szövege lehet.

A tippeknek és az online súgófájloknak mutatóknak kell lenniük, keresés kulcsszavak szerint, amely lehetővé teszi a felhasználó számára, hogy gyorsan megtalálja a szükséges információkat. Bár a gyors fájlok eszközei automatikusan létrehozhatnak mutatókat, jobb, ha ezt manuálisan végezheti el azokat a feltételeket, amelyeket a felhasználók valószínűleg keresnek.

A kép írása Szoftver dokumentáció 8. lépés

öt. Válasszon megfelelő eszközt a dokumentáció létrehozásához. A nyomtatási útmutatók vagy a PDF formátum szövegszerkesztőekben, például a "Word" vagy a "Framemakaker" -ben írhatók, a kézikönyv hosszának és összetettségének függvényében. Tipp fájlokat lehet írni, mint fejlesztési eszközök, mint a "RoboHelp", "Súgó és útmutató", "Doc-to-Help", "Flare", "Helplogix", vagy "HelpServer".

Tippek

A szöveget könnyű elolvasni, a képeket a lehető legközelebb kell elhelyezni a szöveghez, amelyhez tartoznak. Csúsztassa a dokumentációt a szakaszokhoz és a logikai témákhoz. Minden egyes rész vagy téma bizonyos kérdésre van szükség, függetlenül attól, hogy ez egy program vagy feladat. A kapcsolódó kérdéseket fel kell tüntetni, ha szükség esetén hiperhivatkozással kell nézni.
A fent felsorolt dokumentáció létrehozására szolgáló összes eszköz kiegészíthető a képernyőképek programja, például a Scagit, ha a dokumentáció bizonyos számú képernyőképet igényel. Mint a másik dokumentációval, a képernyőképeknek meg kell magyarázniuk, hogy a szoftver hogyan működik, és ne tévesszen meg a felhasználót.
Emellett fontos az írási dokumentáció hangja, különösen akkor, ha a végfelhasználókra íródott. Használja a második arcot "You", a harmadik fél helyett "felhasználók" helyett.

Amire szükséged van

Tool for Writing Dokumentáció / Debula
Eszköz a screenshotok létrehozásához