Why you need moredocumentationEven if you favour working software over comprehensivedocumentationAndy Longshaw, Quantiv Lt...
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• “...
Why do you need documentation? (2)• Because you don’t know what you’re doing– Some bits are clear but other bits are:fuzzi...
What documentation do you need?• NOT 200-page specs• A clean, understandable codebase with cleardomain abstractions at its...
Maps of your world (1)• Tribal Maps– Meaningful to the nativesOr, more usefully, “Fred met adragon here once. It was defin...
Maps of your world (2)• Real maps– Different levels + different info– Contours, major towns, etc.• In the software world…•...
How does this work in practice? (1)• Choose a core, non-volatile subset of your system– If you can’t decide on this then m...
How does this work in practice? (2)• Environments often need attention– Maps of what talks to what in DEV, TST, STG, PRD– ...
How does this work in practice? (3)• Ask some questions…• Who is it for?• When and why will you/they use it?• How long sho...
Don’t forgetAt the end of the day…“It’s all writing”(Pragmatic Programmers)Except when it’s drawing
Upcoming SlideShare
Loading in...5
×

Why you need more documentation

1,855
-1

Published on

Lightning talk by Andy Longshaw for XP Man June 2013

Published in: Technology, Business
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,855
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
1
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • And he got all his files back from GIT…
  • Why you need more documentation

    1. 1. Why you need moredocumentationEven if you favour working software over comprehensivedocumentationAndy Longshaw, Quantiv Ltd.(andrew.longshaw@quantiv.com or andy@blueskyline.com)somePlease keep questions, booing androtten fruit till the end
    2. 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 whatyou’re doing
    3. 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. 4. 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
    5. 5. 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…”
    6. 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, 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
    7. 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 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”
    8. 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 youshould be automating your environment builds…
    9. 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 itaway…– No, don’t leave it on a fileshare to confuse people in thefuture, throw it away…»Now!
    10. 10. Don’t forgetAt the end of the day…“It’s all writing”(Pragmatic Programmers)Except when it’s drawing
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×