Why you need moredocumentationEven if you favour working software over comprehensivedocumentationAndy Longshaw, Quantiv Ltd.(firstname.lastname@example.org or email@example.com)somePlease keep questions, booing androtten fruit till the end
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 whatyou’re doing
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…
What documentation do you need?• NOT 200-page specs• A clean, understandable codebase with cleardomain 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 trickierbits like complex, infrequent config• wiki is usually good for this
Maps of your world (1)• Tribal Maps– Meaningful to the nativesOr, more usefully, “Fred met adragon here once. It was definitelya dragon, not a tiger and he wasable to get away by doing…”
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, cansplit down into Viewpoints and Perspectives– IEEE 1471 or Rozanski & Woods– Especially if there are a lot of NFRs and/or lotsof things outside the software
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 moreproblems 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”
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 youshould be automating your environment builds…
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 itaway…– No, don’t leave it on a fileshare to confuse people in thefuture, throw it away…»Now!
Don’t forgetAt the end of the day…“It’s all writing”(Pragmatic Programmers)Except when it’s drawing
A particular slide catching your eye?
Clipping is a handy way to collect important slides you want to go back to later.