If you can't read please download the document
Upload
jesper-thaning
View
791
Download
0
Embed Size (px)
Citation preview
Kan udviklere dokumentere?13. april 2011
Jesper Thaning, [email protected]
Hvad skal der til for at vi kan opbygge og vedligeholde en brugbar dokumentation?
Opgave 1:Dokumentr dit kkken
Hvad blev der skrevet ned?
Hvilke udfordringer mder I ofte omkring dokumentation?
Dagsorden
Dokumentation p en agil facon
Vrdien af dokumentation
Hvornr skal vi dokumentere?
Tt p brug og kode
Typer af dokumentation
Proces for dokumentation
Dokumenter
Ml for agil udvikling:
Krende software
Understt fremtidige aktiviteter
Scoot Ambler
brug, vedligeholdelse, drift, udvidelser, integration ...
Working software over
comprehensive documentation
Hvad er dokumentation?
Informationer der ikke eksekveres i den normale udfrsel af et program
Kom med nogle eksempler:
Eksempler: Kildekode, tekster i brugergrnsefladen
Hvad er agil dokumentation?
at have akkurat nok dokumentation til den rigtige lser p det rigtige tidspunkt
Hvordan fr vi skrevet og vedligeholdt prcis den dokumentation vi har brug?
Lige s svrt som at have de rigtige features p det rigtige tidspunkt
Hvad skal der til for
On demandJITMen man kan ikke lave JIT hvis man ikke har tnkt over hvordan dokumentation skal produceres.
JIT er ikke wait until we have the problem.
Hvad er agil udvikling?
at have akkurat nok funktionalitet til den rigtige kunde p det rigtige tidspunkt
Lige s svrt som at have de rigtige features p det rigtige tidspunkt
Hvordan fr vi skrevet og vedligeholdt prcis den dokumentation vi har brug?
Hvad skal der til for
On demandJITMen man kan ikke lave JIT hvis man ikke har tnkt over hvordan dokumentation skal produceres.
JIT er ikke wait until we have the problem.
Hvad er der p spil?
Glden ved at bruge relevant dokumentation
Hvad er det der er p spil i forhold til dokumentation?
Har du nogensinde oplevet glden ved at bruge relevant dokumentationHar du nogensinde vre irriteret over at skulle opdatere dokumentationHar du nogensinde bandet over at dokumentation var mangelfuld
Hvis den samme person oplever de to verste vil der vre en incitament til at skrive dokumentation
Hvis det er forskellige personer, krver det en motivationsfaktor.
Hvad er der p spil?
Glden ved at bruge relevant dokumentation
Smerten ved at mangle dokumentation
Hvad er det der er p spil i forhold til dokumentation?
Har du nogensinde oplevet glden ved at bruge relevant dokumentationHar du nogensinde vre irriteret over at skulle opdatere dokumentationHar du nogensinde bandet over at dokumentation var mangelfuld
Hvis den samme person oplever de to verste vil der vre en incitament til at skrive dokumentation
Hvis det er forskellige personer, krver det en motivationsfaktor.
Hvad er der p spil?
Glden ved at bruge relevant dokumentation
Smerten ved at mangle dokumentation
Irritation ved at skulle skrive dokumentation
Hvad er det der er p spil i forhold til dokumentation?
Har du nogensinde oplevet glden ved at bruge relevant dokumentationHar du nogensinde bandet over at dokumentation var mangelfuldHar du nogensinde vre irriteret over at skulle opdatere dokumentation
Hvis den samme person oplever de to verste vil der vre en incitament til at skrive dokumentation
Hvis det er forskellige personer, krver det en motivationsfaktor.
Hvad er der p spil?
Irritation ved at skulle skrive dokumentation
Hvad er det der er p spil i forhold til dokumentation?
Har du nogensinde oplevet glden ved at bruge relevant dokumentationHar du nogensinde vre irriteret over at skulle opdatere dokumentationHar du nogensinde bandet over at dokumentation var mangelfuld
Hvis den samme person oplever de to verste vil der vre en incitament til at skrive dokumentation
Hvis det er forskellige personer, krver det en motivationsfaktor.
One size fits all?
VedligeholdelseKundeprojektProduktudviklingProjektFrameworkLav
Hj
ServiceVrdi af dokumentation
Vrdi dokumentation som krav
Hvad er behovet?Hvor gr det ondt? Hvem mrker det? Hvornr?
Hvad vil dokumentationen koste at vedligeholde?Hvad vil kunden betale for en investering?
Hvordan mler vi vrdien af dokumentation?Tid brugt ved oplring af nye medarbejdere?
Tid brugt ved fremtidig vedligeholdelse af systemet?Fejlrettelser, nyudvikling, idriftsttelser
Kunde med behov for dokumentation
Hvornr dokumenterer vi
i vores proces?
Hvor oplever vi smerten vi manglen p dokumentation?
Hvornr skriver vi dokumentation?
Ideskabelse
Specifikationog design
Test og Implementering
Release
Brug
Beslut om du skal dokumentere og hvad
Skriv dokumentation
Too late!
Hvornr oplever vi smerten vi manglen p dokumentation?
Hvornr skriver vi dokumentation?
Ideskabelse
Specifikationog design
Test og Implementering
Release
Brug
Beslut om du skal dokumentere og hvad
Skriv dokumentation
Too late!
Iterativ proces
Input til nste iteration
Hvornr oplever vi smerten vi manglen p dokumentation?
Tthed p brug og p kode
Jo tttere information er p den operationelle brug og vedligeholdelse af systemet,jo mere vrdifuld er den
Eksempler p: tt p brug og kode
Tt pLngere vk
Brugervejledninger i brugergrnsefladenHjlpe-indeks og manualer
Funktions-test(eks. Cucumber) Dokumenter som beskriver brugsmnstre
Unit-testKodekommentarer
Eksempel: Testscenarie (Cucumber)
Opgave 2: Dokumentr dit kkken
1. Hvorfor? (intention Hvorfor har du et kkken? Hvad vil du opn eller undg?)
2. Hvad? (bestanddele Hvad bestr dit kkken af?)
3. Hvordan? (brug Hvordan bruger du typisk dit kkken)
Hvordan var det at dokumentere denne gang?
Forhbentligt nemmere.
Vigtigheden at have en skabelon og et design for dokumentationen.
Vil vi have en dokumentation der beskriver detaljerne.
Hvad er vi i gang med at dokumentere?
Hvorfor? - intention
Hvad? - bestanddele
Hvordan? - brug
Typer af dokumentation
Eksempler
AfklaringerNotater, analyser, vurderinger
SpecifikationerFunktionstest, unittest, user stories, use cases, prototyper, designdokumenter
ForklaringerSystembeskrivelser, kodekommentarer,
BeskrivelserSystembeskrivelser, regneark, tabeller, diagrammer, overblik
AnvisningerNice to know, driftsanvisninger, supportdokumentation, brugermanualer, hjlpetekster
Hvordan og hvad?
Hvorfor?
Hvad?
Hvordan?
Hvad giver strst vrdi?
Hvilke typer af dokumenter giver strst vrdi i jeres nuvrende projekt?
Hvad vil give strst vrdi i jeres projekt?
Skabelon for dokumentation
Hvilke sprgsml vil vi have svar p?Hvorfor?
Hvad?
Hvordan?
Kodekommentarer
Hvorfor er denne klasse lavet?
/** * */public class ModelManager {....}
Hvor hnger de lavthngende frugter?
Hvor er der lavthngende frugter i forhold til at forbedre dokumentationen? Kildekode?
Refaktorering til at gre navnekonvention entydig.
Proces for dokumentation
KundenBehovDokumentation
giver input til
beskrives i en
opgavekvalitet sikres ved
Feedback
resulterer i
Frdigdokumentation
Udfordringer
Koden er sjldent selvforklarendesvrt at skrive kode der tydligt kommunikerer intention
Krver trning at skrive god dokumentation
Fr vi tid nok skriver vi en lang essay
Vi oplever ting forskelligt visuelt, logisk
Proces for et dokument
Skriv en indholdsfortegnelse
Diskuter med en anden om der er brug for diagrammer
Frste gennemskrivning
F Kunden til at lse det igennemOvervej sammen om der mangler kontekst
Anden gennemskrivningIterr indtil kunden er tilfreds eller i er lbet tr for tid
Sidste gennemlsning af Kunden
Indhold i tekstdokumenter
Husk konteksten for det beskrevne emne
Dokumentr stabile begreber, ikke spekulationer
Forklar indforstede begreber
Undg for mange detaljer de ndrer sig
Dokumentr hvorfor
VersioneringGem historik i dokumentet
Diagrammer
Er vrdifulde, men tager tid at lave
Struktur (hvad)Arkitektur, systemer
Flow (hvordan)Sekvensdiagrammer, brugsmnstre
Frie tegningerVisuel kommunikation
Til blanding af hvad og hvordan
Kan udviklere dokumentere?
Har en kunde med et klart behov
Fr en veldefineret opgaveDesign og arkitektur p dokumentationen
Fr feedback p om opgaven er Done
Ja! Hvis de:
Skab et godt udgangspunkt
Skab konsensus om behov og vrdi
Fjern undvendige informationer. Ryd op!
Fokuser p dokumentation tt p koden
Lav struktur og skabeloner for dokumentation
Dokumenter agilt
Start simpeltTt p brugen af systemetF feedback
http://www.agilemodeling.com/essays/agileDocumentation.htm Scot Ambler.
Agile Documentation, A Pattern Guide to Producing Lightweight Documents for Software, Andreas Rueping