1. file:///mnt/Documents/bestbrains_logo_ansigter.png
Kan udviklere dokumentere?
13. april 2011
Jesper Thaning, BestBrains
jt@bestbrains.dk
file:///mnt/Documents/bestbrainslogo2010_text.png

2. file:///mnt/Documents/bestbrains_logo_ansigter.png
Opgave 1:
Dokumentér dit køkken
file:///mnt/Documents/bestbrainslogo2010_text.png

3. file:///mnt/Documents/bestbrains_logo_ansigter.png
Dagsorden
Dokumentation på en agil facon
Værdien af dokumentation
Hvornår skal vi dokumentere?
Tæt på brug og kode
Typer af dokumentation
Proces for dokumentation
Dokumenter
file:///mnt/Documents/bestbrainslogo2010_text.png

4. file:///mnt/Documents/bestbrains_logo_ansigter.png
Mål for agil udvikling:
Kørende software
”Working software over
comprehensive documentation”
Understøt fremtidige aktiviteter
brug, vedligeholdelse, drift, udvidelser, integration ...
Scoot Ambler
file:///mnt/Documents/bestbrainslogo2010_text.png

5. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er dokumentation?
Informationer der ikke eksekveres i den normale
udførsel af et program
file:///mnt/Documents/bestbrainslogo2010_text.png

6. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er agil dokumentation?
at have akkurat nok dokumentation til den rigtige
læser på det rigtige tidspunkt
file:///mnt/Documents/bestbrainslogo2010_text.png

7. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er agil udvikling?
at have akkurat nok funktionalitet til den rigtige
kunde på det rigtige tidspunkt
file:///mnt/Documents/bestbrainslogo2010_text.png

8. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er der på spil?
Glæden ved at bruge
relevant dokumentation
file:///mnt/Documents/bestbrainslogo2010_text.png

9. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er der på spil?
Glæden ved at bruge Smerten ved at
relevant dokumentation mangle dokumentation
file:///mnt/Documents/bestbrainslogo2010_text.png

10. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er der på spil?
Glæden ved at bruge Smerten ved at
relevant dokumentation mangle dokumentation
Irritation ved at skulle
file:///mnt/Documents/bestbrainslogo2010_text.png
skrive dokumentation

11. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er der på spil?
Irritation ved at skulle
file:///mnt/Documents/bestbrainslogo2010_text.png
skrive dokumentation

12. file:///mnt/Documents/bestbrains_logo_ansigter.png
One size fits all? Værdi af
dokumentation
Høj
Service Framework
Kundeprojekt Projekt
Vedligeholdelse
Produktudvikling
file:///mnt/Documents/bestbrainslogo2010_text.png
Lav

13. file:///mnt/Documents/bestbrains_logo_ansigter.png
Værdi – dokumentation som krav
Hvad er behovet?
Hvor gør det ondt? Hvem mærker det? Hvornår?
Hvad vil dokumentationen koste at vedligeholde?
Hvad vil kunden betale for en investering?
Hvordan måler vi værdien af dokumentation?
Tid brugt ved oplæring af nye medarbejdere?
Tid brugt ved fremtidig vedligeholdelse af systemet?
Fejlrettelser, nyudvikling, idriftsættelser
file:///mnt/Documents/bestbrainslogo2010_text.png

14. file:///mnt/Documents/bestbrains_logo_ansigter.png
Kunde med behov for dokumentation
file:///mnt/Documents/bestbrainslogo2010_text.png

15. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvornår dokumenterer vi
i vores proces?
file:///mnt/Documents/bestbrainslogo2010_text.png

16. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvornår skriver vi dokumentation?
Beslut om du skal
Skriv dokumentation Too late!
dokumentere og hvad
Specifikation Test og
Ideskabelse Release Brug
og design Implementering
file:///mnt/Documents/bestbrainslogo2010_text.png

17. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvornår skriver vi dokumentation?
Beslut om du skal
Skriv dokumentation Too late!
dokumentere og hvad
Specifikation Test og
Ideskabelse Release Brug
og design Implementering
Iterativ proces
Input til næste iteration
file:///mnt/Documents/bestbrainslogo2010_text.png

18. file:///mnt/Documents/bestbrains_logo_ansigter.png
Tæthed på brug og på kode
Jo tættere information er
på den operationelle brug og vedligeholdelse af systemet,
jo mere værdifuld er den
file:///mnt/Documents/bestbrainslogo2010_text.png

19. file:///mnt/Documents/bestbrains_logo_ansigter.png
Eksempler på: tæt på brug og kode
Tæt på Længere væk
Brugervejledninger i Hjælpe-indeks og
brugergrænsef aden
l manualer
Funktions-test Dokumenter som
(eks. Cucumber) beskriver brugsmønstre
Unit-test Kodekommentarer
file:///mnt/Documents/bestbrainslogo2010_text.png

20. file:///mnt/Documents/bestbrains_logo_ansigter.png
Eksempel: Testscenarie (Cucumber)
file:///mnt/Documents/bestbrainslogo2010_text.png

21. file:///mnt/Documents/bestbrains_logo_ansigter.png
Opgave 2: Dokumentér dit køkken
1. Hvorfor? (intention – Hvorfor har du et køkken? Hvad vil du opnå eller undgå?)
2. Hvad? (bestanddele – Hvad består dit køkken af?)
3. Hvordan? (brug – Hvordan bruger du typisk dit køkken)
file:///mnt/Documents/bestbrainslogo2010_text.png

22. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvad er vi i gang med at dokumentere?
Hvorfor? - intention
Hvad? - bestanddele
Hvordan? - brug
file:///mnt/Documents/bestbrainslogo2010_text.png

23. file:///mnt/Documents/bestbrains_logo_ansigter.png
Typer af dokumentation
Eksempler
Afklaringer Notater, analyser, vurderinger
Funktionstest, unittest, user Hvordan og
Specif kationer
i
stories, use cases, prototyper, hvad?
designdokumenter
Forklaringer Systembeskrivelser, Hvorfor?
kodekommentarer,
Beskrivelser Systembeskrivelser, regneark, Hvad?
tabeller, diagrammer, overblik
Anvisninger Nice to know, driftsanvisninger,
supportdokumentation, Hvordan?
brugermanualer, hjælpetekster
file:///mnt/Documents/bestbrainslogo2010_text.png

24. file:///mnt/Documents/bestbrains_logo_ansigter.png
Skabelon for dokumentation
Hvilke spørgsmål vil vi have svar på?
Hvorfor?
Hvad?
Hvordan?
file:///mnt/Documents/bestbrainslogo2010_text.png

25. file:///mnt/Documents/bestbrains_logo_ansigter.png
Kodekommentarer
/**
*
*/
public class ModelManager {
....
}
Hvorfor er denne klasse lavet?
file:///mnt/Documents/bestbrainslogo2010_text.png

26. file:///mnt/Documents/bestbrains_logo_ansigter.png
Hvor hænger de lavthængende frugter?
file:///mnt/Documents/bestbrainslogo2010_text.png

27. file:///mnt/Documents/bestbrains_logo_ansigter.png
Proces for dokumentation
Kunden
Feedback
giver input til
kvalitet sikres ved
Behov Dokumentation
beskrives i en opgave resulterer i
Færdig
dokumentation
file:///mnt/Documents/bestbrainslogo2010_text.png

28. file:///mnt/Documents/bestbrains_logo_ansigter.png
Udfordringer
Koden er sjældent selvforklarende
svært at skrive kode der tydligt kommunikerer intention
Kræver træning at skrive god dokumentation
Får vi tid nok skriver vi en lang essay
Vi oplever ting forskelligt – visuelt, logisk
file:///mnt/Documents/bestbrainslogo2010_text.png

29. file:///mnt/Documents/bestbrains_logo_ansigter.png
Proces for et dokument
Skriv en indholdsfortegnelse
Diskuter med en anden om der er brug for diagrammer
Første gennemskrivning
Få ”Kunden” til at læse det igennem
Overvej sammen om der mangler kontekst
Anden gennemskrivning
Iterér indtil kunden er tilfreds eller i er løbet tør for tid
Sidste gennemlæsning af ”Kunden”
file:///mnt/Documents/bestbrainslogo2010_text.png

30. file:///mnt/Documents/bestbrains_logo_ansigter.png
Indhold i tekstdokumenter
Husk konteksten for det beskrevne emne
Dokumentér stabile begreber, ikke spekulationer
Forklar indforståede begreber
Undgå for mange detaljer – de ændrer sig
Dokumentér ”hvorfor”
Versionering
Gem historik i dokumentet
file:///mnt/Documents/bestbrainslogo2010_text.png

31. file:///mnt/Documents/bestbrains_logo_ansigter.png
Diagrammer
Er værdifulde, men tager tid at lave
Struktur (hvad)
Arkitektur, systemer
Flow (hvordan)
Sekvensdiagrammer, brugsmønstre
Frie tegninger
Visuel kommunikation
Til blanding af hvad og hvordan
file:///mnt/Documents/bestbrainslogo2010_text.png

32. file:///mnt/Documents/bestbrains_logo_ansigter.png
Kan udviklere dokumentere?
Ja! Hvis de:
Har en ”kunde” med et klart behov
Får en veldefineret opgave
”Design” og ”arkitektur” på dokumentationen
Får feedback på om opgaven er ”Done”
Skab et godt udgangspunkt
Skab konsensus om behov og værdi
Fjern unødvendige informationer. Ryd op!
Fokuser på dokumentation tæt på koden
file:///mnt/Documents/bestbrainslogo2010_text.png
Lav struktur og skabeloner for dokumentation

33. file:///mnt/Documents/bestbrains_logo_ansigter.png
Dokumenter agilt
Start simpelt
Tæt på brugen af systemet
Få feedback
http://www.agilemodeling.com/essays/agileDocumentation.htm
Scot Ambler.
Agile Documentation, ”A Pattern Guide to Producing Lightweight
Documents for Software”, Andreas Rueping
file:///mnt/Documents/bestbrainslogo2010_text.png