![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](data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7)
Recommandé
Contenu connexe
Similaire à Why you need more documentation
Similaire à Why you need more documentation (20)
Dernier
Dernier (20)
Why you need more documentation
- 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
Notes de l'éditeur
- And he got all his files back from GIT…