Szoftverdokumentáció – nyomtatott felhasználói kézikönyvek, on-line (online) dokumentáció és súgószöveg, amely leírja a szoftvertermék használatát [1] .
Dokumentum - a dokumentáció eleme: meghatározott közönségnek szánt célzott információ, meghatározott adathordozón (például könyvben, lemezen, gyorstájékoztató kártyán) elhelyezve adott formátumban [1] .
Programdokumentáció - a céltól függően egy program vagy szoftvereszköz fejlesztéséhez, gyártásához, üzemeltetéséhez, karbantartásához szükséges adatokat tartalmazó dokumentumok [2] .
A szoftverdokumentációnak négy fő típusa van:
A tervdokumentáció általában általánosságban írja le a terméket. Anélkül, hogy leírná, hogyan fognak valamit használni, inkább a „miért van ez így” kérdésre válaszol. Például egy tervdokumentumban a programozó leírhatja annak indokait, hogy miért vannak az adatstruktúrák úgy szervezve, ahogy vannak. Leírják azokat az okokat, amelyek miatt egy osztályt bizonyos módon terveztek, kiemelik a mintákat , és néhány esetben még ötleteket is adnak a jövőbeni fejlesztésekre. Ezek egyike sem szerepel a műszaki vagy felhasználói dokumentációban, de mindez nagyon fontos a projekt szempontjából.
Egy program létrehozásakor általában nem elegendő a kód önmagában . Meg kell adni néhány szöveget, amely leírja a kód pontos funkcióit. Az ilyen dokumentációt gyakran közvetlenül a forráskód tartalmazza, vagy azzal együtt szállítják.
Az ilyen dokumentáció rendkívül technikai jellegű, és elsősorban API -k , adatstruktúrák és algoritmusok meghatározására és leírására szolgál .
A műszaki dokumentáció összeállításakor gyakran automatizált eszközöket használnak - dokumentációgenerátorokat , például Doxygen , javadoc , NDoc és mások. Információikat a forráskód speciálisan formázott megjegyzéseiből veszik, és súgó kézikönyveket készítenek valamilyen formátumban, például szövegben vagy HTML -ben .
A dokumentációgenerátorok és a dokumentációs megjegyzések használatát számos programozó kényelmes eszköznek találta, különféle okokból. Ezzel a megközelítéssel különösen a dokumentáció része a forráskódnak, és ugyanazok az eszközök használhatók a program és a dokumentáció elkészítéséhez egyszerre. A dokumentáció naprakészen tartását is megkönnyíti.
A műszaki dokumentációtól eltérően, amely a kódra és annak működésére összpontosít, a felhasználói dokumentáció csak a program használatát írja le.
Ha a termék egy szoftverkönyvtár , akkor a felhasználói dokumentáció és a kóddokumentáció nagyon közeli, szinte egyenértékű fogalmakká válik. De általában nem ez a helyzet.
Általában a felhasználói dokumentáció egy felhasználói kézikönyv , amely leírja a program egyes funkcióit, valamint az adott funkció használatához szükséges lépéseket. A jó felhasználói dokumentáció még ennél is tovább megy, és útmutatást ad arról, hogy mit kell tenni, ha problémák merülnek fel. Nagyon fontos, hogy a dokumentáció ne legyen félrevezető és naprakész. A vezetésnek világos struktúrával kell rendelkeznie; nagyon hasznos, ha van keresztmetszeti index . A logikai koherencia és az egyszerűség szintén nagyon fontos.
Három megközelítés létezik a felhasználói dokumentáció megszervezésére. A bevezető útmutató , amely az új felhasználók számára a leghasznosabb, végigvezeti Önt néhány általános feladat elvégzéséhez szükséges lépéseken. A tematikus megközelítés, amelyben a kézikönyv minden fejezete egy adott témára összpontosít, jobban megfelel a haladó felhasználóknak. Az utolsó, harmadik megközelítésben a parancsok vagy feladatok ábécé-referenciaként vannak megszervezve – gyakran jól fogadják azokat a haladó felhasználók, akik jól tudják, mit keresnek. A felhasználói panaszok általában azzal a ténnyel kapcsolatosak, hogy a dokumentáció e megközelítések közül csak egyet fed le, ezért csak a felhasználók egy csoportja számára alkalmas.
A szoftvertermékek fejlesztői sok esetben csak a beépített súgórendszerre korlátozzák a felhasználói dokumentációt ( angolul online help ), amely a parancsokról vagy menüpontokról tartalmaz súgóinformációkat. Az új felhasználók oktatása és a fejlődő felhasználók támogatása a magánkiadókra van bízva, akik gyakran jelentős segítséget nyújtanak a fejlesztőknek.
Sok alkalmazásnál szükséges, hogy promóciós anyagok legyenek mellette, hogy felkeltsék az emberek figyelmét azáltal, hogy felhívják a figyelmüket a termékre. A dokumentáció ezen formájának célja:
Az egyik jó marketinggyakorlat a szlogen megadása – egy egyszerű fülbemászó kifejezés, amely jól illusztrálja, hogy mit szeretnénk közvetíteni a felhasználónak, valamint leírja azt az érzést , amit a termék kelt.
Gyakran előfordul, hogy a termékdoboz és az egyéb marketinganyagok minden másnál világosabb képet adnak a program használatának lehetőségeiről, módozatairól.
| Szoftverfejlesztés | |
|---|---|
| Folyamat |
|
| Magas szintű koncepciók | |
| Útvonalak |
|
Fejlesztési módszertanok | |
| Modellek |
|
| Figyelemre méltó alakok |
|