Shrnutí na Szoftverdokumentáció és alapelvei

## Bevezetés A szoftverdokumentáció tartalmazza azokat az információkat, amelyek szükségesek egy szoftvertermék megértéséhez, használatához és karbantartásához. Ennek az anyagnak a célja, hogy áttekintést nyújtson a dokumentáció céljáról, arról, hogy milyen formákat ölthet, milyen szabványokat és eszközöket használnak, valamint hogyan lehet hatékonyan létrehozni és újrahasznosítani a dokumentációt. > Definíció: A szoftverdokumentáció szervezett műtermékek (útmutatók, architektúra-leírások, felhasználói kézikönyvek stb.), amelyek célja a tudás átadása egy szoftvertermékről különböző érdekelt feleknek. ## Miért dokumentáljuk a szoftvert - Támogatja a rendszer tesztelését és működésének ellenőrzését. - Támogatja a karbantartást és a fejlesztést (architektúra, interfészek, kommunikációs szabályok ismerete). - Támogatja a végfelhasználókat (útmutatók, oktatóanyagok, GYIK). - Jogi és szerződéses követelmények (a dokumentáció átadása a szerződés része lehet). > Definíció: A felhasználói dokumentáció olyan anyagok összessége, amelyek a végfelhasználók számára készültek, és leírják, hogyan kell használni a rendszert. ### Kinek van szüksége dokumentációra - Tesztelők — a követelmények és tesztesetek reprodukálásához. - Fejlesztők és karbantartó csapat — a tervezés és a függőségek megértéséhez. - Projektmenedzserek — a hatókör nyomon követéséhez és a szabványoknak való megfelelés ellenőrzéséhez. - Ügyfelek — működési és felhasználói utasításokhoz. ## A dokumentáció formája A formát a projekt mérete, komplexitása, a csapat elosztottsága és a várható felhasználó alapján választjuk meg. - Rövid belső jegyzetek és megjegyzések vs. formális kézikönyvek. - Nyomtatott vs. elektronikus dokumentáció (kereshetőség, navigáció, hivatkozások). - Élő, kóddal integrált dokumentáció (automatikusan generált) vs. manuálisan írt. > Definíció: Az elektronikus dokumentáció olyan, elektronikus formátumban terjesztett dokumentáció, amely lehetővé teszi a navigációt, a hiperhivatkozásokat és a keresést. ### Példák a formákra - Felhasználói kézikönyvek és oktatóanyagok. - API referencia kézikönyvek (kódból generált, eszközök segítségével). - Architekturális áttekintések és diagramok. - Hibakezelési és szerviz kézikönyvek. ## Felhasználói dokumentáció felépítése (bevált gyakorlatok alapján) - Bevezetés és cél. - Rendszerkövetelmények (telepítési feltételek). - Alapvető használati forgatókönyvek (lépésről lépésre útmutatók). - Funkciók és korlátozások részletes leírása. - GYIK és hibaelhárítás. | Komponens | Cél | Tartalmi példa | |---|---:|---| | Bevezetés | Megismertetni az olvasót a dokumentum céljával | A célcsoport és a hatókör leírása | | Telepítés | Segíteni a telepítésben | HW/SW követelmények, telepítési lépések | | Használati forgatókönyvek | Megtanítani az alapvető műveleteket | Lépésről lépésre műveletek | | Hibaüzenetek | Segíteni a problémák megoldásában | Hibák listája és javasolt lépések | Érdekesség: A jól megtervezett és a fejlesztési folyamatba integrált dokumentáció akár több tíz százalékkal is csökkenti az új csapattagok beilleszkedéséhez szükséges időt. ## Szabványok és ajánlások - IEEE 1063 (magában foglalja a felhasználói dokumentációra vonatkozó minimális követelményeket, kiterjed az elektronikus formákra is). - Az ajánlások magukban foglalják azokat a követelményeket, hogy a dokumentációnak teljesnek, pontosnak, egyértelműen azonosíthatónak és konkrét célokra (oktatóanyagok, felhasználói dokumentáció, hibaüzenetek) alkalmasnak kell lennie. > Definíció: Az IEEE 1063 egy szabvány, amely meghatározza a szoftver felhasználói dokumentációjának minimális struktúráját, tartalmát és formátumát. ### Mit ajánl az IEEE 1063 szabvány - A hatókör és a célcsoport egyértelmű meghatározása. - Fontos fogalmak meghatározása (kritikus információk, illusztrációk, felhasználó). - Ajánlások a tartalom szervezésére és az elektronikus dokumentumokban való navigációra. ## Eszközök és automatizálás - Dokumentációgenerátorok kódkommentekből (referenc