Dokumentáció és mérési jegyzőkönyv készítése

Az oldal célja, hogy összefoglalja, hogy milyen tartalmi és formai szempontokra kell figyelni egy házi feladat dokumentációjának vagy egy mérés jegyzőkönyvének elkészítése során.

Nem mindegy, hogyan néz ki?
Tanácsok a tartalomhoz
Tanácsok a formázáshoz
Sablonok
További tanácsok

1. Nem mindegy, hogyan néz ki?

Miért fontos egyáltalán figyelmet fordítani a dokumentációra? Mert általában a dokumentáció az, amivel először szembesül valaki, ha megnézi a munkánkat. De miért van egyáltalán szükség dokumentációra, nem elég például csak magát a kódot leadni? A legtöbb esetben nem. Bármilyen munkakörben is dolgozunk majd később, dokumentációt mindig kell készíteni. Ugyanis az elkészült munkának szerves része a dokumentáció, olyan információkat tartalmaz, ami nincs benne a kódban. Mik voltak a főbb döntések, amiket meghoztunk, hogyan kell telepíteni vagy futtatni az alkalmazást, hogyan próbáltuk ki, hogy helyesen működik-e stb. A gyakorlatban a szakmai szempontból jól elvégzett mérnöki munka még csak fél siker (bár a hosszú távú sikernek nélkülözhetetlen fele). Az elvégzett munkát el is kell adni: vagy a főnök, vagy a megrendelő (egyetemen az oktató, mérésvezető) felé. Minél olvashatóbb a dokumentáció (és minél élvezhetőbb a prezentáció vagy bemutató, ha van), annál könnyebb eladni vele a munka eredményét. Ezért "nem mindegy, hogyan néz ki". A dokumentáció olvasója elvárja, elvárhatja azt a kis segítséget, amit a jó (igényes) szerkesztés, formázás és helyesírás tud adni, cserébe azért, hogy megpróbálja megérteni a dokumentáció írójának gondolatmenetét, véleményét, eredményeit. Mit árul el például a következő dokumentáció részlet?

1. ábra: kerülendő dokumentáció

A szövegrészlet tele van durva helyesírási hibákkal (igekötő nincs egybeírva az igével, tucatnyi hiányzó vessző, zárójel előtt rendszeresen hiányzó szóköz). Külön érdemes kiemelni a megoldás-t és Beolvasók gyöngyszemeket. A szöveg a tőmondatok és hibás szerkezetek miatt nehezen olvasható. A formázás se igazán segíti a megértést, a bekezdésekbe tagolás nem követi a szöveg tartalmát. A mondaton belüli teljes betűtípus váltás se túl szerencsés. Összességében ránézve erre a dokumentációra nem túl sokat várhatunk az elkészült munkától sem.

Tanulság: Igénytelen dokumentáció igénytelen munkát sejtet.

Jó dokumentációt nehéz írni, ezt is tanulni és gyakorolni kell. Ezért kell leadni a házi feladatok és labor mérések mellé dokumentációt, ezek megírása során remélhetőleg fejlődik ez a készség is.

2. Tanácsok a tartalomhoz

Fő elv: A dokumentációt olyan részletesen és pontosan kell elkészíteni, hogy az alapján másvalaki pontosan megérthesse, hogy mit végeztünk el, és alkalomadtán végre tudja azt újra hajtani.

Egy két-három oldalnál hosszabb leírásnál már tipikusan megjelennek a következő tartalmi egységek:

• a feladat rövid ismertetése,
• a feladat pontosítása és célok meghatározása,
• az elvégzett munka részletes leírása,
• értékelés, összefoglalás és tanulságok,
• hivatkozások listája.

Természetesen az adott feladat jellegétől függ, hogy az egyes részek mennyire hangsúlyosak, milyen hosszúak. Egy mérés jegyzőkönyvénél a feladat viszonylag pontosan adott, ott azt érdemes részletesen leírni, hogy miért és mit végeztünk el a mérés során. Egy önálló feladatnál fontos, hogy pontosítsuk, hogy mik az elérendő célok, vagy, hogy milyen irodalmat használtunk fel a megoldáshoz.

Egy hosszabb szöveget fejezetekre és alfejezetekre osztunk, hogy könnyebb legyen megérteni. A fejezet címe jellemezze az adott feladatot, pl. RAID tömb létrehozása vagy UML modell készítése. A fejezet elején röviden foglaljuk össze, hogy mit és miért fogunk most csinálni, és csak utána kezdjük el részletezni az egyes lépéseket.

Képet csak akkor rakjunk be, ha tényleg fontos információt hordoz, és segíti a megértést. Egy dokumentáció nem attól lesz precíz és részletes, hogy negyven darab képernyőkép van benne.

Végül pedig mindig törekedjünk a helyes és gördülékeny nyelvhasználatra. Tagolatlan, értelmetlen mondatok nagyon lerontják az érthetőséget és az értékelést. Néhány elrettentő példa korábbi évek hallgatói munkáiból: "HA software csomag a Solaris operációs rendszerre, a Sun Microsystems által készítve.", "(5 9ces rendelekzésreállás egy évre".

3. Tanácsok a formázáshoz

Egy dokumentum esztétikus kinézete majdnem olyan fontos, mint a tartalma. A következőkre mindenképp érdemes figyelni.

• A beadott dokumentációnak legyen fedőlapja, amin rajta van legalább a tárgy neve és kódja, a téma címe, a szerző neve, az elkészítés dátuma. Rövidebb dokumentum esetén elég, ha ezek az első oldal elején szerepelnek.
• A fontos adatokat emeljük ki a szövegből dőlt vagy félkövér formázás használatával. Elektronikus és nyomtatott anyagokban az aláhúzás kerülendő.
• Pár oldalnál hosszabb dokumentum esetén számozzuk a címsorokat, ez segíti az olvasót a dokumentumban való eligazodásban.
• A szöveg szebben néz ki, ha sorkizártra igazítjuk (bár ez eléggé stílus függő, sok helyen balra igazítást alkalmaznak).
• Ábrák beszúrása esetén a következőkre ügyeljünk:
  • Kisebb ábrát célszerű középre rendezni. Az ábra soha ne lógjon ki a margókból.
  • A képek legyenek számozva, legyen aláírásuk, a képekre a számukkal hivatkozzunk (így azok később szabadon mozgathatóak a szövegben).
  • Az ábrán lehetőleg csak a lényeges információ szerepeljen, nem kell például egy képet belerakni a teljes felületről, ha csak az alkalmazás egy konkrét ablakát akarjuk bemutatni.
• A táblázatnak is legyen leírása, ez általában a táblázat felett szokott szerepelni.
• Ha kódrészleteket szúrunk be, akkor azoknál használjunk fix szélességű betűtípusokat (pl. Courier, Consolas), ez segíti a kód olvashatóságát.

3.1. Tanácsok Word használatához

A legfontosabb, hogy használjunk stílusokat. Egységesebb lesz tőle a dokumentum kinézete, és könnyebb később szerkeszteni a dokumentumot. A következő beállítások használatával könnyen leellenőrizhetjük egy Word dokumentum minőségét:

• kapcsoljuk be a dokumentumtérképet, hogy lássuk a dokumentum szerkezetét (Nézet / Dokumentumtérkép vagy View / Document Map),
• jelenítsük meg a Stílusok ablakot (Alt + Ctrl + Shift + S), és ott a Beállítások résznél válasszuk ki a Használatban lévők opciót,
• kapcsoljuk be a formázási inkonzisztencia mutatását (Word beállításai / Speciális / Formázási inkonzisztencia megjelölése vagy Word Options / Advanced / Mark formatting inconsistencies), ilyenkor kék hullámos vonallal jelzi a kézi formázásokat,
• állítsuk be a szöveg nyelvét helyesen, és kapcsoljuk be a helyesírás-ellenőrzést.

Mit látunk ilyenkor egy rosszul formázott dokumentumon (2. ábra)? Bár a szöveg fejezetekre van osztva, a bal oldalon lévő dokumentumtérképben nem ezek jelennek meg, hanem a címlapon szereplő szövegrészek, valamint egy későbbi normál bekezdés szövege. A dokumentum szerzője nyilván nem használt címsorokat és automatikus számozást, hanem kézzel állítgatott be mindent (erre utal például a nullás alfejezet is). A dokumentum szövegénél láthatjuk, hogy nagyjából a teljes szöveg inkonzisztens a használt stílusokkal. A Stílusok ablakban pedig csak két stílus szerepel, holott ránézésre a dokumentumban legalább négy kellene (Címsor 1, Címsor 2, szöveg, kód).

2. ábra: rosszul formázott dokumentum

A stílusokkal való formázáson túl figyeljünk még a következőkre:

• A szöveg tagolására nem az üres sorok beszúrása való, hanem a térköz előtte/utána beállítás a bekezdés tulajdonságainál. (Természetesen ezt is az adott stílusban állítsuk be, és ne egyenként minden szövegrészre.)
• Ha a címsorokat számozzuk, akkor erre használjuk a többszintű lista funkciót.
• Képek aláírásához használjuk a Képaláírás funkciót, amikor pedig hivatkozunk egy képre, azt Kereszthivatkozás segítségével tegyük.

További részletes tanácsok találhatóak a lentebb szereplő Word sablon használati útmutatójában.

3.2. Tanácsok LaTeX használatához

Szerencsére a legtöbb alapvető tudnivalóra figyel a LaTeX környezet és a beépített article sablon is, így csak arra kell ügyelnünk, hogy használjuk a LaTeX funkcióit.

• A fejezetcímekhez és képekhez adjunk meg címkét (\label), és a szövegben a \ref segítségével hivatkozzunk rájuk.
• Irodalomjegyzékhez használjunk BibTeX-et, és a \cite paranccsal hivatkozzunk a szövegben az egyes elemekre.
• A szakdolgozat sablonunk segédletében van egy gyors összefoglaló LaTeX eszközökről és az alapvető parancsokról, azt érdemes átnézni.

4. Sablonok

Microsoft Word:

• Ajánlásképpen álljon itt két Word 2007 sablon: házi feladatokhoz és mérési jegyzőkönyvekhez.
• A sablonok használati útmutatója letölthető DOCX és PDF formátumban.

OpenOffice / LibreOffice:

• A mérési jegyzőkönyv sablon elérhető OpenOffice formátumban is (köszönet érte Vajna Miklósnak).

LaTeX:

• Házi feladat jegyzőkönyv sablon LaTeX formátumban (köszönet érte Cziva Richárdnak).

Diplomaterv sablonok:

• LaTeX
• Word

5. További tanácsok

Az eddigiek csak a legalapvetőbb ismereteket foglalták össze. Ha szeretnénk, hogy tényleg igényes dokumentáció kerüljön ki a kezünkből,  szakdolgozatot vagy TDK dolgozatot készítünk, vagy a későbbi munkánk során bármilyen hosszabb írásos művet kell elkészítenünk, akkor érdemes áttanulmányozni a következő forrásokat is. (A felkiáltójellel megjelölt források hasznosak mindenkinek és elég rövidek, azokat érdemes mindenképp megnézni.)

Helyesírás és nyelvhasználat

• FSF fordítási útmutató (erre érdemes mindenképpen rászánni az időt, később szakdolgozat írásakor vagy majd a napi munkához nagyon jól jön) (!)
• Páncél Róbert. Az idegen szavak toldalékolása... (!)
• MTA Nyelvtudományi Intézet. Helyesírási tanácsadó portál: on-line ellenőrző felület (!)

Dokumentumok felépítése, alapvető tipográfiai ismeretek

• Jeney Gábor. Hogyan néz ki egy igényes dokumentum? BME HIT. 2007. május 9. (nagyon hasznos áttekintő, ha nem olvastuk még, akkor itt az idő) (!)
• Memoir LaTeX csomag dokumentációja: Ez már inkább hosszabb művek (könyv, disszertáció) elkészítéséhez hasznos, vagy a tipográfia iránt érdeklődőknek javasolt. Két részből áll, az első egy általános összefoglaló (memdesign.pdf: a könyvek felépítéséről, lapok elrendezéséről, betűtípusok fajtáiról stb.), a második pedig egy részletes bemutató (memman.pdf: ez már LaTeX-specifikus, de sok mindent lehet belőle akkor is tanulni, ha más környezetet használ valaki)
• Kate L. Turabian. A Manual for Writers of Research Papers, Theses, and Dissertations. 7th edition, University of Chicago Press, 2007 (hogyan álljunk neki egy diplomamunkának, disszertációnak, kutatásnak; a Kindle verzió ára egész elérhető)

További anyagok

• Táblázatok formázása: a booktabs LaTeX csomag PDF dokumentációja tartalmaz nagyon jó általános tanácsokat arról, hogy hogyan lehet kiadói minőségű táblázatokat készíteni (!)
• Dokumentumszerkesztés választható tárgy: LaTeX fóliák

Stílus útmutatók (style guide / style manual)

Főleg angol nyelv esetén a nyelvhasználat és formázási szokások nagyon eltérőek lehetnek nyelv- vagy tudományterülettől függően. Az adott területen alkalmazott szabályokat az úgynevezett stílus útmutatók foglalják össze. Ha angolul írunk, érdemes egy-egy ilyen útmutatót megnézni, hogy tudjuk, hogy mire érdemes a későbbiekben figyelni, valamint, hogy lássuk, hogy mennyi eltérés lehet az egyes javaslatokban.

• European Commission Directorate-General for Translation. English style guide. 7th edition. 2011 (angol nyelv használatára vonatkozó tanácsok)
• IEEE. IEEE Editorial Style Manual (ez már mérnöki területről való, bár nagyon az IEEE folyóirataira fókuszál; a matematikai szövegre és a hivatkozások formázásáról szóló rész részletes)
• University of Chicago. The Chicago Manual of Style. 16th edition. 2010 (elterjedt amerikai angol útmutató, de szabadon nem elérhető)

Utolsó módosítás: 2013.05.29.
Az oldallal kapcsolatos visszajelzéseket Micskei Zoltánnak küldjétek.