Lightning talk by Andy Longshaw for XP Man June 2013

1. Why you need more
documentation
Even if you favour working software over comprehensive
documentation
Andy Longshaw, Quantiv Ltd.
(andrew.longshaw@quantiv.com or andy@blueskyline.com)
some
Please keep questions, booing and
rotten fruit till the end

2. Why do you need documentation? (1)
• Because I don’t know what you’re doing
– Who the hell am I?
– New starter on the team
• “What are the main parts of the system?”
• “Where’s the simple, big picture?”
[pause, blank looks]
• I have been here quite a few times…
– Sheltering manager
• I need a vague idea of what’s going on
• I need a warm fuzzy feeling that you know what
you’re doing

3. Why do you need documentation? (2)
• Because you don’t know what you’re doing
– Some bits are clear but other bits are:
fuzzier, older, broader, outside your domain, etc.
– I have been here quite a few times as well…

4. What documentation do you need?
• NOT 200-page specs
• A clean, understandable codebase with clear
domain abstractions at its heart is a good start…
– …but beyond that…
• Mostly pictures
– Maps of the world, which could be hand-drawn
– Plus some more detailed documentation of trickier
bits like complex, infrequent config
• wiki is usually good for this

5. Maps of your world (1)
• Tribal Maps
– Meaningful to the natives
Or, more usefully, “Fred met a
dragon here once. It was definitely
a dragon, not a tiger and he was
able to get away by doing…”

6. Maps of your world (2)
• Real maps
– Different levels + different info
– Contours, major towns, etc.
• In the software world…
• Simon Brown
– Context, Containers, Components, Classes
• For bigger or more complex systems, can
split down into Viewpoints and Perspectives
– IEEE 1471 or Rozanski & Woods
– Especially if there are a lot of NFRs and/or lots
of things outside the software

7. How does this work in practice? (1)
• Choose a core, non-volatile subset of your system
– If you can’t decide on this then maybe you have more
problems than a lack of documentation
– Be selective!
– Stick them on the wall
– Keep them up to date (see “Be selective!”)
• In general
– let the code tell the detailed “what”
– …and document the high-level “what” and the “why”

8. How does this work in practice? (2)
• Environments often need attention
– Maps of what talks to what in DEV, TST, STG, PRD
– If these artefacts are painful to maintain then maybe you
should be automating your environment builds…

9. How does this work in practice? (3)
• Ask some questions…
• Who is it for?
• When and why will you/they use it?
• How long should it live for?
– Is it enduring or…
– Is it transient
• Draw a diagram to work out your thoughts then throw it
away…
– No, don’t leave it on a fileshare to confuse people in the
future, throw it away…
»Now!

10. Don’t forget
At the end of the day…
“It’s all writing”
(Pragmatic Programmers)
Except when it’s drawing