Capturing Design (When You Really Have To) from XP2016

The Agile Manifesto was partly borne out of valid frustration with “document first” software development methods that seemed to care more about the font size in the documentation set than the value of the software that was delivered. This led to the statement that we value “working software over comprehensive documentation” and a healthy focus on the value of everything we do in software development.

As is so often the case though, we probably overcorrected and we're now often in the situation with 8 year old projects that have lost sight of their fundamental design principles and rationale leading to the very sort of “cargo cult” behaviour that the Agile movement exists to remove. In my design and architecture work with Agile teams, this is something that (as a self-confessed “over-documentor”) I've been working to resolve for years.

In this talk, I discuss what architecture and design information is useful to capture and why. This leads to a set of tangible practices and guidelines to help teams find the right balance in their particular situations.

Transcript

1. EOIN WOODS ENDAVA @eoinwoodz 20160525.2
2. Capturing Design The Problem Why Document Design? How?
3. People move jobs Organisations change Memories Fade Priorities change Knowledge Attrition
4. Knowledge Attrition • “untouchable” code • mysteriously failing tests • odd decisions from long ago • new extensions are always an adventure!
6. Reducing Knowledge Loss Why we need more than code How design information helps
7. Limitations of code The truth not the whole truth Many people don’t read code Organised for machines Mismatch with communication
8. Design as a Record Design for Communication Design for Analysis Using Design Information
9. • • • •
10. • • • •
11. Effective Design Artefacts Principles Pragmatics
12. • M • U • S • I • C • AUDIENCE • PURPOSE “MUSIC”
13. • PRINCIPLES • • DECISIONS • • ELEMENTS RESPONSIBILITIES INTERACTIONS • • •
14. • WORK IN PROGRESS “Indexed” and “checked” are Nat Pryce’s suggestions to add to the “minimal”, “significant”, “usable” set I proposed. These look important to me, but I haven’t thought them through yet.
15. • WHO • TECHNICAL • KNOW • UNDERSTAND • WHAT • TASKS • INFORMATION • CHARACTERISTICS
16. • • • • • • •
17. Low Fidelity High Fidelity Abstract Detailed
18. Fidelity Cost Naming Linking Embedding Shared Versioning Architecturally Evident Coding Shared Tooling But beware limits!
19. George Fairbanks – Just Enough Software Architecture
20. • LINK CODE DOCUMENTATION • • RECENT APPROACH • • ANNOTATE CODE • EXTENDED MODEL
21. https://www.structurizr.com/
22. Effort “Quality” Morning Standup Team Wiki Review Documents Long-term record Regulatory Deliverable Product Documentation
23. Database Calculation Engine Batch Processor Change Notifier User Interface Services
24. Little and Often Create a commons Find evidence of use
25. RECORD • FUTURE NEED TO KNOW • LONGEVITY • SEMANTICS • LINK • ORGANISE COMMUNICATE • WHO WHY • CLARITY • THROW IT AWAY
26. • CODE STORY • WHOLE STORY • KNOWLEDGE ATTRITION • RECORD COMMUNICATE • PRINCIPLES PRAGMATICS
28. RESEARCH DESIGNERS ATTENTION SURVEY
29. Eoin Woods CTO Endava @eoinwoodz www.eoinwoods.info eoin.woods@endava.com
30. • • • http://thumbs.dreamstime.com/z/techn ology-blueprints-23277500.jpg • Design for Communication - http://optymyze.com/