Dokumentazio ona nola egin
1 Sarrera
Gure lan-bizitzan proiektuak egingo ditugu, arazoei irtenbideak bilatzea helburu dutenak, eta horrek hainbat lan tekniko ekarriko ditu: ordenagailu-sare bat konfiguratzea, web-aplikazio bat aldatzea, mugikorretarako aplikazio bat sortzea, azpiegitura bat aztertzea eta hobekuntzak proposatzea...
Proiektu horrekin batera, ohikoa da egindako proiektuaren dokumentazioa aurkeztea, non bezeroaren eskakizunen jasoketa, haien analisia, proiektua gauzatzerakoan hartutako erabakiak eta zergatiak, eta proiektua nola egin den azaldu behar diren.
Interneteko dokumentazioa irakurri badugu ere, ez gaude ohituta gure dokumentazioa sortzera, eta dokumentazio propioa egiten hasten garenean, lortzen dugun emaitza ez da normalean egokia izaten.
Horregatik, dokumentu honetan dokumentazio ona egiteko aholku eta jarraibide batzuk emango dira.
2 Hizkuntza formala/teknikoa
Nahiz eta agerikoa iruditu, dokumentazioetan ezin da hizkuntza kolokiala erabili, beraz beti ikuspegi teknikotik idatzi behar dugu.
Hizkuntza formala erabili behar da eta iritziak, pentsamenduak edo erabakiak aipatzen direnean plural maiestatikoa erabili behar da.
Horrela, idazten duen pertsonak bere iritzia ematea saihesten da, izan ere, proiektuaren atzean normalean profesional talde bat egoten da hartutako erabakiak babesten dituena, beste profesionalen iritzia kontuan hartu dela edo gainbegiratua izan dela.
Proiektu honetan egindako irtenbidea egokia dela uste dugu, zeren …
Iritziak erabiltzen direnean edo “beste batzuk baino hobeak” diren ezarpenak adierazten direnean, beti erabaki horren justifikazioa azaldu behar da, egindako aukeraren arrazoia ulertu ahal izateko.
Jakina, oso garrantzitsua da dokumentuak ez izatea ortografia-akatsik, esaldi amaigaberik, loturarik gabeko esaldirik, …
3 Dokumentuaren formatua
Hasieran erraza iruditu arren, dokumentuaren estiloa zailena izan daiteke, eta horregatik jarraitu behar ditugu hainbat aholku, jarraian azalduko direnak, nahiz eta ez diren bakarrak izango.
3.1 Letra, saretak eta dokumentuaren doikuntzak
Gaur egun, testu-editore gehienek WYSIWYG (ingelesez “What You See Is What You Get”, ikusten duzuna lortzen duzuna da), hala nola Microsoft Word, LibreOffice edo Google Docs, aukera lehenetsi batzuk dituzte, eta horrek dokumentuak bisualki erakargarri egiten ditu eta, printzipioz, ez dugu gauza asko aldatu behar.
Hala ere, hobespen hauek aldatzea erraza da eta dokumentua bisualki erakargarriagoa, pertsonalizatuagoa eta beste dokumentuetatik bereizteko aukera ematen du, irakurleak lehen inpresioa hobetuz.
Enpresetan ohikoa da plantilla pertsonalizatuak sortzea, enpresaren logotipoarekin, korporazio-koloreekin, logotipoan erabiltzen diren letra-motekin, …
Dokumentu honetan bertan ikus daitekeenez, lerroarteak eta paragrafoen arteko tarteak irakurketa errazten dute, beraz konfigurazio hori egokitu beharrekoa da.
Testu-editore bakoitzak konfigurazio batzuk ditu alda daitezkeenak, beraz gomendagarria da denbora bat eskaintzea eskaintzen dituen konfigurazio desberdinak ulertzeko. Goiko irudian Libreoffice programak eskaintzen duen konfigurazioa ikus daiteke.
Garrantzitsua da doikuntzak estiloan bertan aldatzea, ez izenburu edo paragrafo bakoitzean banaka. "1. Izenburua" guztiak berdeak eta tamaina 15 izatea nahi badugu, estilo hori editatu behar dugu. Gero urdinak eta beste letra-mota bat izatea nahi badugu, estiloa aldatzearekin automatikoki aldatuko dira izenburu guztiak, denbora galdu gabe banan-banan aldatzen.
Estiloen konfigurazioak aldatu behar ditugu, dokumentuko testu guztiei aplikatzeko. Ez paragrafoz paragrafo edo izenburuz izenburu joan
3.1.1 Itxura orokorra
Dokumentu honetan ikus daitekeen bezala, ez da beharrezkoa apaingarri handirik dokumentua erakargarria eta irakurtzeko erraza izan dadin.
Gure dokumentuekin begi kritikoa izan behar dugu eta egindako lana ikusi ditugun beste dokumentuekin alderatu.
Gure dokumentuak eskatzen diren ezaugarriak ez baditu, edo guri erakargarria iruditzen ez bazaigu, ez da arraroa pentsatzea dokumentua irakurriko duen irakasleari ere ez zaiola gustatuko.
Itxura bisualak irakurlearen jarrera alda dezake, irakurketa atseginagoa eta errazagoa eginez. Eta alderantziz, irakurketari jarraitzeko gogorik ez izatea eta dokumentua ahalik eta azkarren amaitzea eragin dezake.
Dokumentuaren lehen inpresioak irakasleak zuzentzerakoan alde onetik edo txarretik predisposatu dezake.
3.2 Goiburua, orri-oina eta orri-zenbakiak
Gomendagarria da orri-zenbakia gehitzea dokumentuan, horrela jakin dezakegu dokumentuaren zein zatitan gauden eta orri zehatz bati erreferentzia egin. Normalean orri-zenbakia orri-oinean agertzen da, dokumentu honetan egin den bezala.
Horrez gain, dokumentuaren izenburua, enpresaren izena edo erreferentzia orokor bat gehitu behar da orri-oinean edo goiburuan. Garrantzitsua da atal hauetan erabilitako letra-tamaina testu orokorra baino txikiagoa izatea eta nahikoa tarte egotea testuarekin nahastu ez dadin.
Goiburuan eta orri-oinean letra-tamaina txikiagoa izan behar da, testuarekin nahastu ez dadin.e
Berriro ere, gomendagarria da egindakoa kritikatzea, egindakoaren itxura orokorra egokia den eta irakurketa errazten duen egiaztatzea.
3.3 Irudiak eta haien konposizioa
Irudiak gehitu behar diren dokumentuetan kontuan hartu behar da nola egingo den konposizioa, irudien tamaina eta non kokatuko diren.
3.3.1 Tamaina eta kokapena
Erabiliko dugun irudiaren arabera, dokumentuaren erdialdean jar daiteke, zati handi bat okupatuz, goian ikusi dugun bezala, edo behean agertzen den adibidean bezala.
Kasu honetan Debian banaketaren izena da, baina lehenago programaren pantaila-argazki bat ikusi dugu. Irudiek tamaina egokia izan behar dute, bertako edukia ondo ikusteko.
3.3.2 Irudien azalpena
Dokumentu honetan hainbat irudi gehitu dira, tamaina desberdinetan, paragrafoen ezkerrean zein eskuinean.
Irudi hauek adibide hutsak izan dira, paragrafoari laguntzen dioten irudiak nola jar daitezkeen erakusteko, beti dokumentuaren marjinaren barruan eta testuari tartea utziz. Irudiak ez dira testuaren kontra egon behar marjinetan.
Dokumentuan gehitzen den irudi guztiak azalpen bat izan behar dituzte.
Paragrafoen alboan dauden irudien kasuan, paragrafoek irudiei erreferentzia egingo diete. Irudiak erdian daudenean, komenigarria da irudiaren aurretik zer adierazten duen zehaztea.
Adibidez:
LibreOffice-n estilo guztiak alda ditzakegu paragrafoaren menura joanda, eta gero “Estiloak –> Estiloak kudeatu” menura sartuta, interesatzen zaigun estiloa hautatuz. Adibidez, “Testu gorputza”:
Ikus daitekeen bezala, azaldu nahi denari sarrera labur bat egin zaio, eta ondoren lortutako emaitzaren azalpen-irudi bat gehitu da.
3.3.3 Irudien mozketa
Irudi batean zerbait zehatzari erreferentzia egin nahi diogunean, egokiena ez da pantaila osoaren argazkia jartzea, baizik eta aipatzen ari garen leihoaren argazkia soilik egitea.
Horretarako, Windows-eko “Mozketa tresna” (Herramienta de Recortes) aplikazioak aukera ematen du hautatutako leihoaren mozketa perfektua egiteko, goiko irudian ikus daitekeen bezala, modua aukeratuz. Horrela, interesatzen zaigun leihoa bakarrik lortuko dugu, mozketa txarra saihestuz, eta arreta benetan garrantzitsua den horretan zentratzea lortuko dugu.
Irudi baten barruan zerbait zehaztu nahi badugu, gomendagarria da atal hori kolore batez (gorriz, adibidez) inguratzea, nabarmenagoa izan dadin. Zenbait kasutan gezi txiki bat ere gehi daiteke aukera erakusteko.
Leiho jakin batzuen pantaila-argazkiak edo moztuak ditugunean, komenigarria izan daiteke borde txiki bat gehitzea, gaur egungo mahaigaineko leihoek atzealde zuria erabiltzen dutelako eta dokumentuaren atzealde zuriaren aurka ez litzatekeelako ondo ikusiko.
Ondoren, irudi bera ertza gabe eta ertzarekin ikus daiteke:
Ikus daitekeenez, borde gabeko irudiak “mozketa zakarra” efektua ematen du, eta ertza duenean argiago ikusten da moztutako atala dela.
Leihoen pantaila-argazkiei ertza jartzea gomendagarria da
4 Erreferentziak
Dokumentu guztietan egon daitezke (eta egon behar dute) beste dokumentazio batzuetara, kopiatutako edo hainbat iturritatik jasotako testuetara erreferentziak, eta horrela bada, erreferentziatu egin behar da.
“Beste lan batzuetara egindako erreferentziak oso garrantzitsuak dira lanbide askotako literaturan; bakoitzak informazio hori testuan sartzeko bere modua diseinatu du, eta horrek aipamenen formatu estandarizatuak sortzea ekarri du.” (Iturria: Wikipedia)
Goiko paragrafoan ikus daitekeen bezala, testua komatxo artean dago, goiko marjinarekin, eta amaieran informazioaren jatorria eta webgunerako esteka agertzen dira. Beste dokumentuetako testuak edo aipamenak erreferentziatzeko modu desberdinak daude, baina ez gara horretan sakonduko.
Beraz, dokumentu bat sortzerakoan beste testu batzuei erreferentzia egiten badiegu, adierazi beharko genuke, eta are gehiago kopiatu eta itsatsi egiten dugunean. Objektiboak izan behar dugu eta irakurleari jakinarazi behar diogu irakurri duen hori ez dela gure sorkuntza, eta beste egile baten testua erabili dela. Horregatik, jatorrizko egilea edo informazioa atera den webgunea erreferentziatu behar da.
Beste adibide bat izan daiteke: Isaac Newtonek Hookeri idatzi ziona: “Urrunago ikusi badut, erraldoien sorbaldetan eserita egon naizelako da.”, horrek esan nahi du berak ere bere ikasketak eta lorpenak aurreko zientzialari handien ekarpenak erabiliz lortu zituela. Ikus daitekeenez, erreferentzia komatxo artean dago eta letra etzanez idatzita dago.
5 Dokumentua entregatu aurretik berrikusi
Dokumentu tekniko bat ez da egun batean egiten den zerbait, idazketan zehar hainbat etapa izaten ditu, eta horregatik, entregatu aurretik idatzitakoa berrikusi behar da.
Oso agerikoa dirudien arren, urrats hau ez da normalean egiten, dokumentua idazten duenak pentsatzen duelako idazketa egiterakoan ondo egin zuela. Egia izan daitekeen arren, irakurketa beranduago beti aterako ditu idatzitakoaren akatsak eta kontraesanak.
Zenbait kasutan, hasierako idazketan ortografia-akatsak zuzentzea ahaztu zaigu, dokumentuaren egitura ez da egokiena izan, edo bi paragrafo jarraian gauza bera azaldu dugu.
Horregatik, proiektua egin duten kide guztiek dokumentua irakurri eta zuzenketak egin behar dituzte azken entregaren aurretik bezeroari.
6 Dokumentuaren eguneraketa
Dokumentu tekniko bat “izaki bizidun” bat izaten da normalean, proiektuaren zerbitzu/komponente desberdinek eguneraketak, aldaketak edo erabilerarik ez izatea jasaten dutenean eguneratu behar dena.
Dokumentazio teknikoak azpiegitura/programa/web-aren egungo egoera zehaztasunez islatu behar du, bestela ez du balio informazio zaharkitua izateak, eta are okerragoa izan daiteke.
Dokumentazio honek konpainiako kide berriei azpiegitura/programa/web-aren egoera ezagutzeko balioko die, edo kanpoko enpresa berri bati bertan aldaketak egiteko.
Dokumentu baten elementuak
7 Dokumentu baten elementuak
Dokumentu tekniko batek gutxienez honako elementu hauek izan behar ditu.
7.1 Azala
Dokumentu tekniko batek azala izan behar du, bertan egindakoaren irudi bat, enpresaren izena/logotipoa eta bezeroaren izena/logotipoa gehitu daitezke… Hemen plantilla korporatiboaren araberakoa izango da.
Oso itxura txarra ematen du azalean bereizmen/resoluzio baxuko irudi bat jartzeak.
Azalean dokumentua egin duten pertsonen izenak, egindako data, eta kasu batzuetan ikasgaiaren izena ere gehitu behar dira…
7.2 Aurkibidea
Dokumentuaren hasieran aurkibide bat gehitu behar da, bertan tituluak eta agertzen diren orriak islatu behar dira.
Aurkibidea testu-editoreak automatikoki sortzen du, baina horretarako atal bakoitza bere “Izenburu/Goiburua” egokiarekin sortu behar da. Dokumentuan aldaketak egiten badira, aurkibidea eguneratu behar da goiburu berriak, orriak, … islatzeko.
7.3 Sarrera
Dokumentu honetan egin den bezala, sarrera bat egon behar da, bertan dokumentu osoan zehar azalduko dena adieraziz.
Dokumentu tekniko batean, proiektua burutu duen taldeko kideen funtzioak ere gehitu ohi dira.
7.4 Egindakoaren analisia eta azalpenak
Proiektuan egindakoa zehazten den zatia da. Maila desberdineko goiburuetan banatu behar da. Hau da, dokumentuan hierarkia bat sortu behar da, atal garrantzitsuenak bereiziz eta horien barruan egindako lanak edo azalpenak banatuz.
Atal hauen hierarkia testu-editoreek eskaintzen dituzten “goiburu/izenburu” moten bidez egiten da, eta hori oso ondo islatzen da aurkibidean.
Aurkibidea begiratuta bakarrik azter daiteke dokumentu bat ondo egituratuta dagoen ala ez.
7.5 Laburpena/ondorioak
Dokumentazioetan amaierako laburpen bat gehitzen da, bertan dokumentuan zehar zehaztutako puntu garrantzitsuenak jasotzen dira.
Atal hau normalean amaieran egoten da, orri bereizi batean egon daiteke, eta bere izenak dioen bezala, dokumentuaren puntu garrantzitsuenak laburbiltzen ditu.
Era berean, aukera bat da egindakoari balioa emateko, bezeroari puntu indartsuak erakutsiz, egindakoaren irudi positiboa uzteko. Honek etorkizuneko kontratazioetan lagun dezake.
8 Laburpena
Dokumentu honetan zehar ikusi den bezala, dokumentu tekniko bat egiteko hainbat alderdi kontuan hartu behar dira, nahiz eta hasiera batean errazak iruditu, prozesu bat da ikasi behar dena eta denbora eskatzen duena.
Egindako lanarekin kritikoak izatea garrantzitsua da, izan ere, irakurri (eta zuzendu) behar duen pertsonak informazio asko lor dezake idatzi dutenen inguruan: erabilitako dedikazioa, egindako gainbegiratzea, gaitasun teknikoa, gaitasun transbertsal idatzia, …
Errubrika
9 Ebaluazio-irizpidea
Ondorengo ebaluazio-irizpidea erabiliko da entregatutako dokumentuak zuzentzeko, bai zereginetan bai erronketan dokumentazio teknikoa eskatu denean.
Gomendagarria da irizpidea irakurtzea, dokumentu tekniko osoa nola zuzenduko den kontuan izateko.
| Bikaina (86 - 100) | Oso ona (60 - 85) | Hobetzekoa (41 - 59) | Oso hobetzekoa (0 - 40) | |
|---|---|---|---|---|
| Itxura bisuala 10% | Dokumentua bisualki oso ondo dago. Azala, marjinak, izenburuak, irudiak, koloreak… dokumentua irakurtzeko erraza egiten dute. Antolatuta dago eta liburu/dokumentu profesional baten itxura du. | Dokumentua bisualki ondo dago, baina badaude guztiz zaindu ez diren atal batzuk. Intentzioa ona dela nabaritzen da, baina ez dago guztiz landuta. | Dokumentuak itxura hobea izan dezake. Atal batzuk salbatzen dira, baina orokorrean zaintza eskasa da. | Dokumentua desordenatuta dago. Bisualki ez du espero den estetika. Hautatutako irudi, izenburu eta koloreek irakurketa zailtzen dute. |
| Idazketa eta ortografia akatsak 20% | Dokumentua ondo idatzita dago, koherentzia eta argitasuna dago ideiak adieraztean. Ez dago ortografia-akatsik eta erabilitako hizkuntza zehatza da. | Dokumentua ondo idatzita dago. Ia ez dago ortografia-akatsik (3 baino gutxiago) eta erabilitako hizkuntza egokia da. | Erdi-koherentea eta irakurgarria. Hizkuntza sinplea eta zehaztugabea. Ortografia, puntuazio edo sintaxi-akats batzuk (4-8). | Dokumentua ez da koherentea. Ortografia eta sintaxi-akats ugari. Irakurtzeko zaila da erabilitako hizkuntza eta/edo akatsengatik. |
| Lanaren kalitatea, ikerketa, egiazkotasuna, hizkuntza teknikoa, atalen ordena, … 50% | Ikerketan jasotako edukiak zuzenak eta kalitate onekoak dira. Egindakoa erraz ulertzen da eta gida gisa erabil daiteke egindakoa errepikatzeko. Benetako proiektu baten ondoren bezeroari entregatutako dokumentu tekniko baten itxura du. | Ikerketan jasotako eduki gehienak zuzenak eta kalitate onekoak dira. Datuak partzialki kontrastatuak eta egiazkoak. Oro har dokumentu ona da, nahiz eta atal batzuk hobetu beharko liratekeen pausoak errepikatzeko. | Ikerketan jasotako eduki batzuk ez dira zuzenak eta kalitate hobea izan dezakete. Emandako pausoak desordenatuta daude, ez dira guztiz errealitatera egokitzen edo jarraitzeko zailak dira. | Ikerketan jasotako edukiak kalitate txarrekoak dira. Datu faltsuak erabiltzen dira kontrastatu gabe. Dokumentuak ez du balio egindako lanaren ideia izateko ezta behar izanez gero errepikatzeko. Pausoak, azalpenak edo proiektuaren atal batzuk falta dira. |
| Sarrera 10% | Sarrera ondo idatzita dago. Dokumentua irakurtzeko gogoa ematen du. Laburra da baina egindako guztia adierazten du. | Sarrera ondo dago, eta idazketa ona da, baina hobea izan zitekeen. | Sarrera zuzena da, baina hobetu daiteke. | Sarrera gaizki idatzita dago. Ez du dokumentua irakurtzeko gogorik ematen eta egin beharrekoen inguruko informazioa falta da. |
| Laburpena eta ondorioak 10% | Egindakoa bikain laburbiltzen da eta egindako lanaren garrantziaren ondorioak gehitzen dira. Azaldutakoa ez da sarreraren errepikapena ezta egindako pauso guztien errepikapena ere. | Laburpena eta ondorioak zuzenak dira. Idazketa ona da, baina gehiago zaindu zitekeen. | Laburpena hobetu daiteke. Ez du ondorioak gehitzen edo adierazitakoak eskasak dira. | Laburpena eskasa da eta ez du ondorio zuzenik gehitzen. Sarrera imitatzen du edo egindako pauso guztiak berriro deskribatzen ditu. |