file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Kan udviklere dokumentere?13. april 2011

Jesper Thaning, BestBrainsjt@bestbrains.dk

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Opgave 1:Dokumentér dit køkken

file:///mnt/Documents/bestbrainslogo2010_text.png

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Mål for agil udvikling:

Kørende software

Understøt fremtidige aktiviteter

Scoot Ambler

brug, vedligeholdelse, drift, udvidelser, integration ...

”Working software over comprehensive documentation”

file:///mnt/Documents/bestbrainslogo2010_text.png

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

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

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

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvad er der på spil?

Glæden ved at bruge relevant dokumentation

Smerten ved at mangle dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvad er der på spil?

Glæden ved at bruge relevant dokumentation

Smerten ved at mangle dokumentation

Irritation ved at skulle skrive dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvad er der på spil?

Irritation ved at skulle skrive dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

One size fits all?

Vedligeholdelse

Kundeprojekt

Produktudvikling

Projekt

Framework

Lav

Høj

Service

Værdi af dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Kunde med behov for dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvornår dokumenterer vi i vores proces?

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvornår skriver vi dokumentation?

IdeskabelseSpecifikationog design

Test og Implementering Release Brug

Beslut om du skal dokumentere og hvad

Skriv dokumentation Too late!

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvornår skriver vi dokumentation?

IdeskabelseSpecifikationog design

Test og Implementering Release Brug

Beslut om du skal dokumentere og hvad

Skriv dokumentation Too late!

Iterativ procesInput til næste iteration

file:///mnt/Documents/bestbrainslogo2010_text.png

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Eksempler på: tæt på brug og kode

Tæt på Længere væk

Brugervejledninger i brugergrænsefl aden

Hjælpe-indeks og manualer

Funktions-test(eks. Cucumber)

Dokumenter som beskriver brugsmønstre

Unit-test Kodekommentarer

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Eksempel: Testscenarie (Cucumber)

file:///mnt/Documents/bestbrainslogo2010_text.png

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

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Typer af dokumentationEksempler

Afklaringer Notater, analyser, vurderinger

Specifi kationer Funktionstest, unittest, user stories, use cases, prototyper, designdokumenter

Forklaringer Systembeskrivelser, kodekommentarer,

Beskrivelser Systembeskrivelser, regneark, tabeller, diagrammer, overblik

Anvisninger Nice to know, driftsanvisninger, supportdokumentation, brugermanualer, hjælpetekster

Hvordan og hvad?

Hvorfor?

Hvad?

Hvordan?

file:///mnt/Documents/bestbrainslogo2010_text.png

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Kodekommentarer

Hvorfor er denne klasse lavet?

/**

*

*/

public class ModelManager {

....

}

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Hvor hænger de lavthængende frugter?

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Proces for dokumentation

Kunden

Behov Dokumentation

giver input til

beskrives i en opgave

kvalitet sikres ved

Feedback

resulterer i

Færdigdokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

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

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 igennemOvervej sammen om der mangler kontekst

Anden gennemskrivningIteré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

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

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

file:///mnt/Documents/bestbrains_logo_ansigter.png

Kan udviklere dokumentere?

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”

Ja! Hvis de:

Skab et godt udgangspunktSkab konsensus om behov og værdi

Fjern unødvendige informationer. Ryd op!

Fokuser på dokumentation tæt på koden

Lav struktur og skabeloner for dokumentation

file:///mnt/Documents/bestbrainslogo2010_text.png

file:///mnt/Documents/bestbrains_logo_ansigter.png

Dokumenter agilt

Start simpeltTæt på brugen af systemet

Få feedbackhttp://www.agilemodeling.com/essays/agileDocumentation.htm

Scot Ambler.

Agile Documentation, ”A Pattern Guide to Producing Lightweight Documents for Software”, Andreas Rueping