Why I don’t write documentation! November 25, 2010 05:55 about 1 year ago
Du skal dokumentere dit arbejde! De fleste mennesker i udviklingsafdelingen bliver helt stille. Og med god grund. Hvis nogle vil vide hvad der sker mellem mine krøllede parenteser kan de bare læse kildekoden. Selvom det kaldes kode kan det faktisk læses.
Alt for mange gange har jeg været tvunget til at læse en såkaldt software dokumentation enten som en del af et review eller som en del af et nyt projekt. Endnu flere gange er jeg blvet bedt om at skrive dokumentation til en system del som er omfattende eller direkte ubrugelig pga. overdreven kompleksitet.
Typisk består den tekniske dokumentation at et par diagrammer og detaljeret beskrivelser af alle implicerede klasse med attributter og operationer. Endda med underskrift og alting. Dokumenterne er udfyldt med en masse information om hvad klasserne er fulde af og gerne en statisk model men meget lidt om hvilken typer af opgaver de skal løse. Jeg bliver altid lidt klogere men der mangler noget?
Hvorfor gider vi at blive ved at fabrikere software dokumentation? Vi får ikke penge for at udføre flotte grafer hvor man kan se to systemer med en linje i mellem. Jeg kan til nød forstå en tegning hvor man kan se de dynamiske relationer mellem flere objekter, men præcis denne tegning er aldrig med med.
Der findes værktøjer med det formål at skabe dels dokumentation dels en kodebase gennem kodegenererin. Resultatet er igen en statisk model med attribut diagrammer der ikke beskiver den dynamiske adfærd og du siger alligevel til din projektleder at du har dokumenteret alt. Det er hvad jeg kalder dum dokumentation og er rent CO2 udslip.
Hvis i dit team siger at alt er dokumenteret er det et forkert svar på et helt forkert spørgsmål. Hvis du dokumentere alt vil det jo betyde du vægter alle komponenter i systemer lige meget. I ethvert system er der nogle aspekter som er mere vigtige end andre.
Kunsten i dokumentationen er at finde de særlige elementer der kræver specielt opmærksomhed og at kunne kommunikere denne viden. Alt god dokumentation er kortfattet. Kun hvis dokumentation er kort vil nogen læse og forstå den. Kun hvis dokumentation er kort vil du gider at holde den ajour. Kun hvis dokumentation er kort vil du tale om den, du vil aldrig fortælle det hele.
Det er op til din dygtighed som udvikler og kommunikator at finde de elementer der kræver dokumentation. Det beror på målgruppen samt den faglige ekspertise målgruppen er af besiddelse af. Hvis du forsøger at dokumentere alt kan du måske bare ikke bestemte dig for hvad der er vigtigt.
Nøglen til god kommunikation er at fremhæve de vigtige ting der er at sige.
By Frank Vilhelmsen - 2 tags: logs development - Add comment