Upgrade to Pro — share decks privately, control downloads, hide ads and more …

"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

Birgitta Boeckeler

June 09, 2017
Tweet

More Decks by Birgitta Boeckeler

Other Decks in Technology

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 full-size slide

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

    View full-size slide

  3. DESCRIBING SOFTWARE

    View full-size slide

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

    View full-size slide

  5. PURPOSE of
    documentation?

    View full-size slide

  6. For the sake
    of a PROCESS.

    View full-size slide

  7. PURPOSE of
    documentation?

    View full-size slide

  8. Create a
    COMMON
    UNDERSTANDING.
    1

    View full-size slide

  9. The wall of
    COMMON
    UNDERSTANDING.
    Containers &
    Tech Stack
    Environments
    Components …


    Up for grabs!

    View full-size slide

  10. Surface and
    understand
    COMPLEXITY.
    2

    View full-size slide

  11. … …

    Data schema
    migrations
    Synching
    behavior

    Design of
    storage module

    View full-size slide

  12. INFO GRAPHICS.

    View full-size slide

  13. “WIDGET” KITS.

    View full-size slide

  14. Create EMPATHY.
    3

    View full-size slide

  15. Empathy between
    TECH DECISION
    MAKERS and
    developers.

    View full-size slide

  16. “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 full-size slide

  17. Empathy between
    PRODUCT PEOPLE and
    developers.

    View full-size slide

  18. Empathy with OTHER
    TECHNOLOGISTS.

    View full-size slide

  19. Help our
    FUTURE SELVES
    make informed
    DECISIONS.
    4

    View full-size slide

  20. 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 full-size slide

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

    View full-size slide

  22. Describe the
    PROBLEM, not just
    the SOLUTION.

    View full-size slide

  23. CREATIVE
    problem
    SOLVING.
    5

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  29. @birgitta410

    View full-size slide