Pro Yearly is on sale from $80 to $50! »

"We're Agile, we don't do documentation"

"We're Agile, we don't do documentation"

Slides as presented at "The Lead Developer" conference 2017 in London

645147e9899005bc24e5ff7d65a1d60c?s=128

Birgitta Boeckeler

June 09, 2017
Tweet

Transcript

  1. “WE’RE AGILE, WE DON’T DO DOCUMENTATION” @birgitta410 B i r

    g i t t a B ö c k e l e r
  2. None
  3. “Documenting Software Architectures – Views and Beyond” 2nd edition, 2011;

    Clements, Bachmann, Bass, Garlan, Ivers, Little, Merson, Nord, Stafford
  4. None
  5. None
  6. None
  7. None
  8. None
  9. None
  10. DESCRIBING SOFTWARE

  11. None
  12. WHERE ARE YOU? 1:1 UML diagrams No documentation at all

    “Self- documenting code” Tests are readable specification
  13. PURPOSE of documentation?

  14. For the sake of a PROCESS.

  15. PURPOSE of documentation?

  16. Create a COMMON UNDERSTANDING. 1

  17. None
  18. The wall of COMMON UNDERSTANDING. Containers & Tech Stack Environments

    Components … … … Up for grabs!
  19. Surface and understand COMPLEXITY. 2

  20. … … … Data schema migrations Synching behavior … Design

    of storage module
  21. INFO GRAPHICS.

  22. “WIDGET” KITS.

  23. Create EMPATHY. 3

  24. Empathy between TECH DECISION MAKERS and developers.

  25. “Working on software without guidance, without documentation, is anxiety-producing” https://medium.com/@duretti/no-flex-zone-empathy-driven-development-aebf4d8cf7cf

    Empathy with EACH OTHER.
  26. Empathy between PRODUCT PEOPLE and developers.

  27. Empathy with OTHER TECHNOLOGISTS.

  28. Help our FUTURE SELVES make informed DECISIONS. 4

  29. Architecture DECISION records. http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions “Without understanding the rationale (…), only

    two choices: 1. Blindly accept the decision. 2. Blindly change it.”
  30. LIGHTWEIGHT architecture DECISION records. https://github.com/npryce/adr-tools

  31. Describe the PROBLEM, not just the SOLUTION.

  32. CREATIVE problem SOLVING. 5

  33. None
  34. None
  35. None
  36. None
  37. But how do we keep it UP TO DATE?!

  38. @kaeff

  39. As LITTLE as possible. Make it VISIBLE. Include in RITUALS.

    Create OWNERSHIP through COLLABORATION.
  40. Help our FUTURE SELVES make informed DECISIONS. Surface and understand

    COMPLEXITY. Create COMMON UNDERSTANDING. CREATIVE problem SOLVING. Create EMPATHY.
  41. <> Code THE TRUTH HOW-TOs HISTORY MAPS CREATIVE THINKING

  42. “Individuals and interactions” “Business people and developers work together daily”

    “Face to face communication” “Attention to technical excellence and good design” “Simplicity”
  43. @birgitta410