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

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

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
3. “Documenting Software Architectures – Views and Beyond” 2nd edition, 2011; Clements, Bachmann, Bass, Garlan, Ivers, Little, Merson, Nord, Stafford
10. DESCRIBING SOFTWARE
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
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
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