Successfully reported this slideshow.

Kan udviklere dokumentere april2011

807 views

Published on

  • Be the first to comment

  • Be the first to like this

Kan udviklere dokumentere april2011

  1. 1. Kan udviklere dokumentere? 13. april 2011 Jesper Thaning, BestBrains [email_address]
  2. 2. Opgave 1: Dokumentér dit køkken
  3. 3. Dagsorden <ul><li>Dokumentation på en agil facon
  4. 4. Værdien af dokumentation
  5. 5. Hvornår skal vi dokumentere?
  6. 6. Tæt på brug og kode
  7. 7. Typer af dokumentation
  8. 8. Proces for dokumentation
  9. 9. Dokumenter </li></ul>
  10. 10. Mål for agil udvikling: Kørende software Understøt fremtidige aktiviteter Scoot Ambler brug, vedligeholdelse, drift, udvidelser, integration ... ” Working software over comprehensive documentation”
  11. 11. Hvad er dokumentation? Informationer der ikke eksekveres i den normale udførsel af et program
  12. 12. Hvad er agil dokumentation? at have akkurat nok dokumentation til den rigtige læser på det rigtige tidspunkt
  13. 13. Hvad er agil udvikling ? at have akkurat nok funktionalitet til den rigtige kunde på det rigtige tidspunkt
  14. 14. Hvad er der på spil? Glæden ved at bruge relevant dokumentation
  15. 15. Hvad er der på spil? Glæden ved at bruge relevant dokumentation Smerten ved at mangle dokumentation
  16. 16. Hvad er der på spil? Glæden ved at bruge relevant dokumentation Smerten ved at mangle dokumentation Irritation ved at skulle skrive dokumentation
  17. 17. Hvad er der på spil? Irritation ved at skulle skrive dokumentation
  18. 18. One size fits all? Lav Høj Værdi af dokumentation
  19. 19. Værdi – dokumentation som krav <ul><li>Hvad er behovet? </li><ul><li>Hvor gør det ondt? Hvem mærker det? Hvornår? </li></ul><li>Hvad vil dokumentationen koste at vedligeholde? </li><ul><li>Hvad vil kunden betale for en investering? </li></ul><li>Hvordan måler vi værdien af dokumentation? </li><ul><li>Tid brugt ved oplæring af nye medarbejdere?
  20. 20. Tid brugt ved fremtidig vedligeholdelse af systemet? </li><ul><li>Fejlrettelser, nyudvikling, idriftsættelser </li></ul></ul></ul>
  21. 21. Kunde med behov for dokumentation
  22. 22. Hvornår dokumenterer vi i vores proces?
  23. 23. Hvornår skriver vi dokumentation? Ideskabelse Specifikation og design Test og Implementering Release Brug Beslut om du skal dokumentere og hvad Skriv dokumentation Too late!
  24. 24. Hvornår skriver vi dokumentation? Ideskabelse Specifikation og design Test og Implementering Release Brug Beslut om du skal dokumentere og hvad Skriv dokumentation Too late! Iterativ proces Input til næste iteration
  25. 25. 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
  26. 26. Eksempler på: tæt på brug og kode Tæt på Længere væk Brugervejledninger i brugergrænsefladen Hjælpe-indeks og manualer Funktions-test (eks. Cucumber) Dokumenter som beskriver brugsmønstre Unit-test Kodekommentarer
  27. 27. Eksempel: Testscenarie (Cucumber)
  28. 28. 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)
  29. 29. Hvad er vi i gang med at dokumentere? Hvorfor? - intention Hvad? - bestanddele Hvordan? - brug
  30. 30. Typer af dokumentation Eksempler Afklaringer Notater, analyser, vurderinger Specifikationer 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?
  31. 31. Skabelon for dokumentation <ul><li>Hvilke spørgsmål vil vi have svar på? </li><ul><li>Hvorfor?
  32. 32. Hvad?
  33. 33. Hvordan? </li></ul></ul>
  34. 34. Kodekommentarer <ul><li>Hvorfor er denne klasse lavet? </li></ul>/** * */ public class ModelManager { .... }
  35. 35. Hvor hænger de lavthængende frugter?
  36. 36. Proces for dokumentation giver input til beskrives i en kvalitet sikres ved resulterer i Kunden Behov Dokumentation opgave Feedback Færdig dokumentation
  37. 37. Udfordringer <ul><li>Koden er sjældent selvforklarende </li><ul><li>svært at skrive kode der tydligt kommunikerer intention </li></ul><li>Kræver træning at skrive god dokumentation
  38. 38. Får vi tid nok skriver vi en lang essay
  39. 39. Vi oplever ting forskelligt – visuelt, logisk </li></ul>
  40. 40. Proces for et dokument <ul><ul><li>Skriv en indholdsfortegnelse
  41. 41. Diskuter med en anden om der er brug for diagrammer
  42. 42. Første gennemskrivning
  43. 43. Få ”Kunden” til at læse det igennem </li><ul><li>Overvej sammen om der mangler kontekst </li></ul><li>Anden gennemskrivning </li><ul><li>Iterér indtil kunden er tilfreds eller i er løbet tør for tid </li></ul><li>Sidste gennemlæsning af ”Kunden” </li></ul></ul>
  44. 44. Indhold i tekstdokumenter <ul><li>Husk konteksten for det beskrevne emne
  45. 45. Dokumentér stabile begreber, ikke spekulationer
  46. 46. Forklar indforståede begreber
  47. 47. Undgå for mange detaljer – de ændrer sig
  48. 48. Dokumentér ”hvorfor”
  49. 49. Versionering </li><ul><li>Gem historik i dokumentet </li></ul></ul>
  50. 50. Diagrammer <ul><li>Er værdifulde, men tager tid at lave
  51. 51. Struktur (hvad) </li><ul><li>Arkitektur, systemer </li></ul><li>Flow (hvordan) </li><ul><li>Sekvensdiagrammer, brugsmønstre </li></ul><li>Frie tegninger </li><ul><li>Visuel kommunikation
  52. 52. Til blanding af hvad og hvordan </li></ul></ul>
  53. 53. Kan udviklere dokumentere? <ul><li>Har en ”kunde” med et klart behov
  54. 54. Får en veldefineret opgave </li><ul><li>”Design” og ”arkitektur” på dokumentationen </li></ul><li>Får feedback på om opgaven er ”Done” </li></ul>Ja! Hvis de: Skab et godt udgangspunkt <ul><li>Skab konsensus om behov og værdi
  55. 55. Fjern unødvendige informationer. Ryd op!
  56. 56. Fokuser på dokumentation tæt på koden
  57. 57. Lav struktur og skabeloner for dokumentation </li></ul>
  58. 58. Dokumenter agilt <ul>Start simpelt Tæt på brugen af systemet Få feedback </ul><ul><li>http://www.agilemodeling.com/essays/agileDocumentation.htm Scot Ambler.
  59. 59. Agile Documentation, ”A Pattern Guide to Producing Lightweight Documents for Software”, Andreas Rueping </li></ul>

×