• Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
372
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
0
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide
  • Hvad skal der til for at vi kan opbygge og vedligeholde en brugbar dokumentation?
  • Hvad blev der skrevet ned? Hvilke udfordringer møder I ofte omkring dokumentation?
  • Kom med nogle eksempler: Eksempler: Kildekode, tekster i brugergrænsefladen
  • Hvordan får vi skrevet og vedligeholdt præcis den dokumentation vi har brug? Lige så svært som at have de rigtige features på det rigtige tidspunkt Hvad skal der til for On demand JIT Men man kan ikke lave JIT hvis man ikke har tænkt over hvordan dokumentation skal produceres. JIT er ikke wait until we have the problem.
  • Lige så svært som at have de rigtige features på det rigtige tidspunkt Hvordan får vi skrevet og vedligeholdt præcis den dokumentation vi har brug? Hvad skal der til for On demand JIT Men man kan ikke lave JIT hvis man ikke har tænkt over hvordan dokumentation skal produceres. JIT er ikke wait until we have the problem.
  • Hvad er det der er på spil i forhold til dokumentation? Har du nogensinde oplevet glæden ved at bruge relevant dokumentation Har du nogensinde være irriteret over at skulle opdatere dokumentation Har du nogensinde bandet over at dokumentation var mangelfuld Hvis den samme person oplever de to øverste vil der være en incitament til at skrive dokumentation Hvis det er forskellige personer, kræver det en motivationsfaktor.
  • Hvad er det der er på spil i forhold til dokumentation? Har du nogensinde oplevet glæden ved at bruge relevant dokumentation Har du nogensinde være irriteret over at skulle opdatere dokumentation Har du nogensinde bandet over at dokumentation var mangelfuld Hvis den samme person oplever de to øverste vil der være en incitament til at skrive dokumentation Hvis det er forskellige personer, kræver det en motivationsfaktor.
  • Hvad er det der er på spil i forhold til dokumentation? Har du nogensinde oplevet glæden ved at bruge relevant dokumentation Har du nogensinde bandet over at dokumentation var mangelfuld Har du nogensinde være irriteret over at skulle opdatere dokumentation Hvis den samme person oplever de to øverste vil der være en incitament til at skrive dokumentation Hvis det er forskellige personer, kræver det en motivationsfaktor.
  • Hvad er det der er på spil i forhold til dokumentation? Har du nogensinde oplevet glæden ved at bruge relevant dokumentation Har du nogensinde være irriteret over at skulle opdatere dokumentation Har du nogensinde bandet over at dokumentation var mangelfuld Hvis den samme person oplever de to øverste vil der være en incitament til at skrive dokumentation Hvis det er forskellige personer, kræver det en motivationsfaktor.
  • Hvor oplever vi smerten vi manglen på dokumentation?
  • Hvornår oplever vi smerten vi manglen på dokumentation?
  • Hvornår oplever vi smerten vi manglen på dokumentation?
  • Hvordan var det at dokumentere denne gang? Forhåbentligt nemmere. Vigtigheden at have en skabelon og et design for dokumentationen. Vil vi have en dokumentation der beskriver detaljerne.
  • Hvad giver størst værdi? Hvilke typer af dokumenter giver størst værdi i jeres nuværende projekt? Hvad vil give størst værdi i jeres projekt?
  • Hvor er der lavthængende frugter i forhold til at forbedre dokumentationen? Kildekode? Refaktorering til at gøre navnekonvention entydig.

Transcript

  • 1. file:///mnt/Documents/bestbrains_logo_ansigter.png Kan udviklere dokumentere? 13. april 2011 Jesper Thaning, BestBrains jt@bestbrains.dkfile:///mnt/Documents/bestbrainslogo2010_text.png
  • 2. file:///mnt/Documents/bestbrains_logo_ansigter.png Opgave 1: Dokumentér dit køkkenfile:///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 Dokumenterfile:///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 Amblerfile:///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 programfile:///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 tidspunktfile:///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 tidspunktfile:///mnt/Documents/bestbrainslogo2010_text.png
  • 8. file:///mnt/Documents/bestbrains_logo_ansigter.png Hvad er der på spil? Glæden ved at bruge relevant dokumentationfile:///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 dokumentationfile:///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 skullefile:///mnt/Documents/bestbrainslogo2010_text.png skrive dokumentation
  • 11. file:///mnt/Documents/bestbrains_logo_ansigter.png Hvad er der på spil? Irritation ved at skullefile:///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 Produktudviklingfile:///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ættelserfile:///mnt/Documents/bestbrainslogo2010_text.png
  • 14. file:///mnt/Documents/bestbrains_logo_ansigter.png Kunde med behov for dokumentationfile:///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 Implementeringfile:///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 iterationfile:///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 denfile:///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 Kodekommentarerfile:///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? - brugfile:///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ælpeteksterfile:///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 dokumentationfile:///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, logiskfile:///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 dokumentetfile:///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 hvordanfile:///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å kodenfile:///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 Ruepingfile:///mnt/Documents/bestbrainslogo2010_text.png