"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
   

   View Slide

2. View Slide

3. “Documenting Software Architectures – Views and Beyond”
   2nd edition, 2011; Clements, Bachmann, Bass, Garlan, Ivers, Little, Merson, Nord, Stafford
   

   View Slide

4. View Slide

5. View Slide

6. View Slide

7. View Slide

8. View Slide

9. View Slide

10. DESCRIBING SOFTWARE
    

    View Slide

11. View Slide

12. WHERE ARE YOU?
    1:1 UML
    diagrams
    No
    documentation
    at all
    “Self-
    documenting
    code”
    Tests are
    readable
    specification
    

    View Slide

13. PURPOSE of
    documentation?
    

    View Slide

14. For the sake
    of a PROCESS.
    

    View Slide

15. PURPOSE of
    documentation?
    

    View Slide

16. Create a
    COMMON
    UNDERSTANDING.
    1
    

    View Slide

17. View Slide

18. The wall of
    COMMON
    UNDERSTANDING.
    Containers &
    Tech Stack
    Environments
    Components …
    …
    …
    Up for grabs!
    

    View Slide

19. Surface and
    understand
    COMPLEXITY.
    2
    

    View Slide

20. … …
    …
    Data schema
    migrations
    Synching
    behavior
    …
    Design of
    storage module
    

    View Slide

21. INFO GRAPHICS.
    

    View Slide

22. “WIDGET” KITS.
    

    View Slide

23. Create EMPATHY.
    3
    

    View Slide

24. Empathy between
    TECH DECISION
    MAKERS and
    developers.
    

    View Slide

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.
    

    View Slide

26. Empathy between
    PRODUCT PEOPLE and
    developers.
    

    View Slide

27. Empathy with OTHER
    TECHNOLOGISTS.
    

    View Slide

28. Help our
    FUTURE SELVES
    make informed
    DECISIONS.
    4
    

    View Slide

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.”
    

    View Slide

30. LIGHTWEIGHT
    architecture
    DECISION records.
    https://github.com/npryce/adr-tools
    

    View Slide

31. Describe the
    PROBLEM, not just
    the SOLUTION.
    

    View Slide

32. CREATIVE
    problem
    SOLVING.
    5
    

    View Slide

33. View Slide

34. View Slide

35. View Slide

36. View Slide

37. But how do we
    keep it
    UP TO DATE?!
    

    View Slide

38. @kaeff
    

    View Slide

39. As LITTLE as possible.
    Make it VISIBLE.
    Include in RITUALS.
    Create OWNERSHIP through
    COLLABORATION.
    

    View Slide

40. Help our FUTURE SELVES
    make informed DECISIONS.
    Surface and understand
    COMPLEXITY.
    Create
    COMMON UNDERSTANDING.
    CREATIVE problem SOLVING.
    Create EMPATHY.
    

    View Slide

41. <> Code
    THE
    TRUTH
    HOW-TOs
    HISTORY
    MAPS
    CREATIVE
    THINKING
    

    View Slide

42. “Individuals and interactions”
    “Business people and developers
    work together daily”
    “Face to face communication”
    “Attention to
    technical excellence and
    good design”
    “Simplicity”
    

    View Slide

43. @birgitta410
    

    View Slide