Download - Kan udviklere dokumentere april2011

Transcript

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