Kan udviklere dokumentere april 2011
-
Upload
bestbrainsdk -
Category
Documents
-
view
391 -
download
0
Transcript of Kan udviklere dokumentere april 2011
file:///mnt/Documents/bestbrainslogo2010_text.png
file:///mnt/Documents/bestbrains_logo_ansigter.png
Kan udviklere dokumentere?13. april 2011
Jesper Thaning, [email protected]
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