146 Kezdőlap - Webszerkesztés - Dokumentáció
ujdomainek.hu

Dokumentáció

záródolgozathoz, vizsgaprojekthez

Jegyzet

Amikor szoftverfejlesztőként akár a záródolgozat keretében, akár már egy "éles" munka részeként dokumentációt kell írnunk egy elkészült programunkhoz, gyakran ez komolyabb kihívásnak számít, mint magának a szoftvernek az elkészítése. Az alább olvasható ötletgyűjtemény e munka megkönnyítéséhez szeretne kiindulási alapot, inspirációt, kiegészítő gondolatokat kínálni. Első közelítésből megnézzük a lehetséges főbb fejezeteket, majd ezt követően áttekintjük a legfőbb formai elvárásokat, végül pedig kiemelünk olyan tartalmi kérdéseket, melyek programnyelvtől, és környezettől függően ugyan, de jó eséllyel helyet kaphatnak a dokumentációban.

Checklista Az oldal alján pedig található egy Önellenőrző lista, mellyel checkboxos felületen ellenőrizhető, hogy tartalmi és formai alapon milyen minőségű a dokumentációnk aktuális állapota. A felület százalékos értékelést és abból számolva körülbelüli osztályzatot is mutat.

Főbb fejezetek

Egy záródolgozatként, vagy vizsgaprojektként készített programhoz a dokumentációban az alábbi fejezeteket érdemes kialakítani.

1. Bevezetés, témaválasztás indoklása, szakmai célkitűzés

Itt azt célszerű leírni, hogy miről szól az elkészült program, milyen szakmai és/vagy hasznosulási céllal került megvalósításra, és mi indokolta a téma választását a készítő személy szemszögéből, élethelyzetéből nézve. Ez a bevezetés nagyjából egy szűk oldalban megvalósítható.

2. Fejlesztői dokumentáció

A fejlesztői dokumentáció a fejlesztés menetéről szól. Azért készül, hogy ha valaki szakmabeliként érdeklődik a program sajátosságai iránt, akkor beleláthasson a technikai részletekbe. Mivel szakmabeli olvassa, nem szükséges "szájbarágósnak" lenni, sőt kifejezetten az a cél, hogy szakmai nyelvezetet használjunk benne. Alapvetően 5 fő alfejezete van: A tesztdokumentáció nem arról szól, hogy hol nem működik jól a program - hiszen a program mindenhol jól működik, különben nincs kész! -, hanem arról, hogy hogyan viselkedik különböző környezetekben, illetve nem optimális használat esetén. Ilyenformán érdemes benne leírni, hogy milyen hardverkörnyezetben (számítógépen, vagy épp mobileszközön), valamint milyen operációs rendszeren, illetve pl. böngészőben, milyen képfelbontás mellett lett kipróbálva, és ott milyen sajátosságokat tapasztaltunk a teszt során. Továbbá ebben a részben kap helyet a helyes működés bizonyítása is, amikor kipróbáljuk a programunkat különböző rossz adatokkal, vagy éppen nagyon sok adattal, esetleg adatok nélkül, és bemutatjuk, hogy ezekre a helyzetekre hogyan - pl. milyen üzenetekkel - reagál a programunk.
A fejlesztési lehetőségek ismertetése arra biztosít lehetőséget, hogy elmondjuk, mi az, amilyen funkciókkal a program a későbbiekben tovább bővíthető, gazdagítható. Ezzel egyrészt jelezhetjük, hogy tudjuk, mit nem tud még a programunk, másrészt érzékeltethetjük, hogy a program nem öncélúan, kizárólag a vizsga miatt készült, hanem további terveink vannak vele.
Ez a fejezet korrekt kifejtettség esetén jellemzően 16-20 oldal, melyből a tesztdokumentáció 4-6 oldal.

3. Felhasználói dokumentáció

A felhasználói dokumentáció a felhasználónak szól. Annak a felhasználónak, aki azt sem tudja, hova csöppent, mit tart a kezében, mit kezdjen vele, és azt hogyan tegye. Éppen ezért ez a dokumentációrész nagyon részletes, nagyon "szájbarágós", és nagyon a nulláról indul. Nagyjából onnan például, hogy "ez egy számítógépes szoftver". Vagy hogy ez egy "közösségi weblap". És el kell benne mondani, milyen eszközön használható, milyen szoftver kell hozzá, hogyan kell letölteni, telepíteni, elindítani... stb.
E fejezet 6 részre bontható: A hibajelzések magyarázata erős átfedést tartalmazhat a tesztdokumentáció helyes programműködést bizonyító részével. Az eltérés leginkább a megfogalmazásban, a nyelvezetben érhető tetten, ám a kiemelt képernyőrészletek, mint ábrák - melyek a különféle hibajelzéseket mutatják be - mindkét helyen felhasználhatóak. Itt lehet elmesélni, miként viselkedik a program pl. hiányosan kitöltött űrlapok, vagy éppen hibás regisztrációs, illetve bejelentkezési adatok megadása esetén, valamint találatot nem eredményező keresési feltételek mellett.
Az információkérés lehetőségének biztosítására érdemes a szerző által egy kifejezetten erre a célra létrehozott e-mail címet feltüntetni. Elegánsabb esetben az e-mail címen túl (és nem pedig helyette!) a program részeként egy űrlapot is létesíthetünk pl. Kapcsolat címszó alatt, amit szintén tüntessünk fel a dokumentációban.
Ez a fejezet, ha minden kívánt tartalmi elemet magába foglal, kevéssé úszható meg 10-12 oldalnál kevesebből. Ellenkező esetben érdemes végiggondolni a fentieket, vajon mi maradt ki a leírásból.

4. Összefoglalás, köszönetnyilvánítás

A dokumentáció záró fejezete a némiképp szubjektív gondolatoknak adhat teret. Itt összefoglalható, hogy saját megítélésünk szerint mennyire sikerült megvalósítanunk az első fejezetben megfogalmazott szakmai célokat, hogyan látjuk az elkészült munkánkat, mint kész projektet. Írhatunk arról, mik jelentették a legnagyobb kihívásokat, és mik voltak azok a dolgok, amikből a legtöbbet tanultuk. Vázolhatjuk a programunk utóéletéről alkotott elképzeléseinket, vagyis azt, hogy miként szeretnénk a folytatásban hasznosítani a művünket.
Továbbá itt lehet helye a köszönetnyilvánításnak is, melyben a megemlítendő személyek tekintetében nemcsak szakmai szempontok alapján érdemes gondolkodni, hiszen egyrészt családtagjaink, szeretteink vélhetően toleranciával viseltettek irántunk, míg mi tanultunk, másrészt esetleg szüleink, eltartóink anyagi áldozatokat is hoztak szakmai fejlődésünk értekében.
A fejezet jellemzően 1-2 oldal terjedelmű szokott lenni.

5. Irodalomjegyzék

E részben kell felsorolni azokat a szakmai forrásokat, amiket a munkánk során felhasználtunk. Itt éppúgy érdemes megemlíteni néhány könyvet (szerző, cím, kiadó, kiadás éve), mint ahogyan weboldalakat is felsorolhatunk.
Szakmai könyveket akkor is érdemes megemlíteni az irodalomjegyzékben, ha csak érintőlegesen használtunk ilyeneket, mert emelik a dolgozatunk fényét. Ugyanakkor csak olyan könyvet jelöljünk meg, amelyről szükség szerint valóban tudunk legalább egy-két mondatot mondani a programunk szóbeli bemutatása alkalmával.
Weboldalak esetén nem elegendő megadni az oldal fő címét, hanem teljes mélységű URL-eket kell megjelölni. Pl. helytelen az infojegyzet.hu egyszerű megnevezéssel történő említése. A helyes jelölés: Az irodalomjegyzék általában rá szokott férni 1 oldalra.

Formai elvárások

A dokumentáció formai elvárásainak tekintetében a következő irányelveket célszerű követni.

Tartalmi kérdések

A fejlesztői dokumentációban gyakran találhatóak nagyon jellemzően hiányos, vagy teljesen kimaradó elemek. Ilyenek lehetnek az alábbi példákban szereplőek. Végül nézzünk meg néhány egyedi, de mégis tipikus, tartalomra vonatkozó lehetséges gondolatot a felhasználói dokumentáció kapcsán, mert általában itt szokott gyakori kérdés lenni, hogy "Mit írjak még bele?" Természetesen a fenti ötletek alapján minden hasonló gondolatmenet helyet kaphat a vonatkozó dokumentációban. Újabb ötletek "beszerzése" pedig leghatékonyabban úgy valósítható meg, ha odaadjuk valamely ismerősünknek tesztelni a programot, és közben figyeljük, jegyzeteljük a cselekedeteit, és különösen a felmerülő kérdéseit. Éljünk a lehetőséggel: teszteltessünk!

Önellenőrző lista

Az alábbi összefoglaló 37 szempontja alapján ellenőrizheti, mennyire precíz a dokumentációja. Jelölje meg azokat a négyzeteket, amelyeknek a tartalma saját megítélése szerint rendben van, majd a lista alatt tekintse meg a dokumentáció ezek alapján történő értékelését.
Checklista

    Bevezetés

  1. Megindokoltam a témaválasztásomat, leírtam az okokat.
  2. Leírtam, hogy milyen funkciójú programot terveztem készíteni.
  3. Megjelöltem a célközönséget, vagyis hogy kiknek szánom a programot.

    Fejlesztői dokumentáció

  4. Megindokoltam, miért volt szükség a program elkészítésére, és miben más, mint más hasonló létező program.
  5. Ismertettem a fejlesztőkörnyezetem hardverét.
  6. Ismertettem a fejlesztés során használt szoftvereket.
  7. Megindokoltam, hogy miért azt a programnyelvet, és miért azt a fejlesztőkörnyezetet választottam, amit.
  8. Részletesen írtam az adatszerkezetről. Adatbázis használata esetén bemutattam a táblákat, a táblák egyes mezőit, és készítettem ábrát a táblák közötti kapcsolatok személtetéséhez.
  9. Bemutattam legalább 4 tipikus algoritmusomat.
  10. A tesztdokumentációmban legalább 6 különböző körülményről, esetről, hibakezelésről írtam.
  11. Leírtam, hogy a biztosítottam tesztelői hozzáférést.
  12. Írtam fejlesztési legalább 2 fejlesztési lehetőséget.
  13. A fejlesztői dokumentációm legalább 16 oldal.

    Felhasználói dokumentáció

  14. Néhány mondatban bemutattam, hogy a felhasználó milyen programot tart a kezében.
  15. Leírtam, hogy a program használatához miféle hardver eszközre van szükség.
  16. Leírtam, hogy a program használatához milyen szoftverekre van szükség.
  17. Leírtam, hogyan lehet letölteni, telepíteni, elindítani a programot.
  18. Részletesen ismertettem a program használatát.
  19. Ismertettem, mely funkciók érhetőek el szabadon, és mihez szükséges regisztráció.
  20. Minden a szövegbeviteli mező esetén leírtam, hogy ott mit vár el szoftver. Írtam a hosszról, megengedett karakterekről, ékezetes betűkről, kis- ill, nagybetűkről.
  21. Szemléltetésként beszúrtam legalább 5 képernyőképet, vagy annak egy-egy részletét.
  22. Bemutattam, milyen hibajelzéseket kaphat a felhasználó a tevékenysége során.
  23. Külön ismertettem az admin felhasználó és az felület lehetőségeit.
  24. Adtam elérhetőséget információkérés lehetőségéhez.
  25. A felhasználói dokumentációm legalább 10 oldal.

    Összefoglalás

  26. Leírtam, hogyan értékelem az elkészült munkámat.
  27. Írtam róla, hogy hogyan látom a programom hasznosulását a továbbiakban (a vizsgától függetlenül).

    Irodalomjegyzék

  28. Az irodalomjegyzékben megneveztem legalább két általam is használt szakmai könyvet
  29. Az irodalomjegyzékben teljes mélységű URL-eket jelöltem meg az oldalak címével együtt, nem pedig csak domain neveket.

    Formai szempontok

  30. A dokumentációm másfeles sortávú, 12-es betűméretű.
  31. A bekezdéseimre beállítottam a sorkizárt formátumot.
  32. Tagolásként címsorokat alkalmaztam.
  33. A fő fejezetek mindegyike új oldalon kezdődik.
  34. A tartalomjegyzéket a címsorok alapján a szövegszerkesztőm készítette.
  35. Az első oldal(ak) kivételével a folytatásban mindenhol látható az oldalszám az oldal tetején, vagy alján. Automatikus oldalszámozást használtam.
  36. Munkámat helyesírás szempontjából ellenőriztettem valaki hozzáértővel. A szükséges korrekciókat elvégeztem.
  37. Az elkészült dokumentációt PDF formátumba mentettem, és a PDF állományt felmásoltam adathordozóra a beadandó programom mellé.
A dokumentáció értéke a fenti jelölőnégyzetek kiválasztása alapján
0%
Ez az érték osztályzatban kifejezve
elégtelen (1)
Nyilván a záródolgozat teljes értékelését a program és a dokumentáció együtt adja, és mindkettőben a tartalmi és szubjektív tényezők is sokat számítanak. Éppen ezért az itt mutatott értékelés szigorúan tájékoztató jellegű, a végleges értékelésre nézve nem vonhatók le belőle direkt következtetések.
előző oldal random oldal következő oldal


2021-05-07 23:46:24 Admin Köszönöm, ha Ön lesz az első, aki megírja ide véleményét, észrevételét, kérdését ezzel a lappal kapcsolatban.




Új hozzászólás:
E-mail cím:


Erre a címre küldjük ki a hozzászólás jóvá- hagyásához szükséges linket. Az e-mail címet sehol nem tesszük közzé.

Név:


Ez a név fog megjelenni az Ön hozzászólásai mellett.

Mennyi tizenegy + három?
Számjegyekkel írja be!



Ez a robotok beírása elleni védelem miatt szükséges ellenőrzés.


© infojegyzet.hu, 2021. április