際際滷

際際滷Share a Scribd company logo
Why	
 you	
 need	
 more	
 
documenta/on	
 
Even	
 if	
 you	
 favour	
 working	
 so8ware	
 over	
 comprehensive	
 
documenta/on	
 
	
 
Andy	
 Longshaw,	
 Advanced	
 Legal	
 Ltd.	
 
(andy.longshaw@advancedcomputerso8ware.com	
 or	
 
andy@blueskyline.com)	
 
some	
 
Please	
 keep	
 ques/ons,	
 booing	
 and	
 
roEen	
 fruit	
 /ll	
 the	
 end
Why	
 do	
 you	
 need	
 documenta/on?	
 (1)	
 
≒ Because	
 I	
 dont	
 know	
 what	
 youre	
 doing	
 
Who	
 the	
 hell	
 am	
 I?	
 
New	
 starter	
 on	
 the	
 team	
 
≒ What	
 are	
 the	
 main	
 parts	
 of	
 the	
 system?	
 
≒ Wheres	
 the	
 simple,	
 big	
 picture?	
 
[pause,	
 blank	
 looks]	
 
≒ I	
 have	
 been	
 here	
 quite	
 a	
 few	
 /mes	
 
Sheltering	
 manager	
 
≒ I	
 need	
 a	
 vague	
 idea	
 of	
 whats	
 going	
 on	
 
≒ I	
 need	
 a	
 warm	
 fuzzy	
 feeling	
 that	
 you	
 know	
 what	
 
youre	
 doing
Why	
 do	
 you	
 need	
 documenta/on?	
 (2)	
 
≒ Because	
 you	
 dont	
 know	
 what	
 youre	
 doing	
 
Some	
 bits	
 are	
 clear	
 but	
 other	
 bits	
 are:	
 fuzzier,	
 
older,	
 broader,	
 outside	
 your	
 domain,	
 etc.	
 
I	
 have	
 been	
 here	
 quite	
 a	
 few	
 /mes	
 as	
 well
What	
 documenta/on	
 do	
 you	
 need?	
 
≒ NOT	
 200-足page	
 specs	
 
≒ A	
 clean,	
 well	
 understandable	
 codebase	
 with	
 clear	
 
domain	
 abstrac/ons	
 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	
 documenta/on	
 of	
 trickier	
 
bits	
 like	
 complex,	
 infrequently	
 needed	
 con鍖g	
 
≒ wiki	
 is	
 usually	
 good	
 for	
 this
Maps	
 of	
 your	
 world	
 (1)	
 
≒ Tribal	
 Maps	
 
Meaningful	
 to	
 the	
 na/ves	
 
Or,	
 more	
 usefully,	
 Fred	
 met	
 a	
 
dragon	
 here	
 once.	
 It	
 was	
 de鍖nitely	
 
a	
 dragon,	
 not	
 a	
 /ger	
 and	
 he	
 was	
 
able	
 to	
 get	
 away	
 by
Maps	
 of	
 your	
 world	
 (2)	
 
≒ Di鍖erent	
 levels	
 +	
 di鍖erent	
 info	
 
 Contours,	
 major	
 towns,	
 etc.	
 
≒ In	
 the	
 so8ware	
 world	
 
≒ Simon	
 Brown	
 
 Context,	
 Containers,	
 Components,	
 Classes	
 
≒ For	
 bigger	
 or	
 more	
 complex	
 systems,	
 
can	
 split	
 down	
 into	
 Viewpoints	
 and	
 
Perspec/ves	
 
 IEEE	
 1471	
 or	
 Rozanski	
 &	
 Woods	
 
 Especially	
 if	
 there	
 are	
 a	
 lot	
 of	
 NFRs	
 and/or	
 
lots	
 of	
 things	
 outside	
 the	
 so8ware
How	
 does	
 this	
 work	
 in	
 prac/ce?	
 (1)	
 
≒ Choose	
 a	
 core,	
 non-足vola/le	
 subset	
 
 If	
 you	
 cant	
 decide	
 on	
 this	
 then	
 maybe	
 you	
 have	
 more	
 
problems	
 than	
 a	
 lack	
 of	
 lightweight	
 docs	
 
 Be	
 selec/ve!	
 
 S/ck	
 them	
 on	
 the	
 wall	
 
 Keep	
 them	
 up	
 to	
 date	
 (see	
 Be	
 selec/ve!)	
 
≒ Otherwise	
 
 let	
 the	
 code	
 tell	
 the	
 detailed	
 what	
 
 and	
 document	
 the	
 high-足level	
 what	
 and	
 the	
 why
How	
 does	
 this	
 work	
 in	
 prac/ce?	
 (2)	
 
≒ Environments	
 o8en	
 need	
 aEen/on	
 
 Maps	
 of	
 what	
 talks	
 to	
 what	
 in	
 DEV,	
 TST,	
 STG,	
 PRD	
 
 If	
 these	
 docs	
 are	
 painful	
 to	
 maintain	
 then	
 maybe	
 you	
 
should	
 be	
 automa/ng	
 your	
 environment	
 builds
How	
 does	
 this	
 work	
 in	
 prac/ce?	
 (3)	
 
≒ Ask	
 some	
 ques/ons	
 
≒ 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,	
 dont	
 leave	
 it	
 on	
 a	
 鍖leshare	
 to	
 confuse	
 people,	
 throw	
 it	
 
away	
 
損Now!
Dont	
 forget	
 
	
 
At	
 the	
 end	
 of	
 the	
 day	
 
	
 
Its	
 all	
 wri/ng	
 	
 
(Pragma'c	
 Programmers)	
 
	
 
Except	
 when	
 its	
 drawing

More Related Content

Why you need more documentation

  • 1. Why you need more documenta/on Even if you favour working so8ware over comprehensive documenta/on Andy Longshaw, Advanced Legal Ltd. (andy.longshaw@advancedcomputerso8ware.com or andy@blueskyline.com) some Please keep ques/ons, booing and roEen fruit /ll the end
  • 2. Why do you need documenta/on? (1) ≒ Because I dont know what youre doing Who the hell am I? New starter on the team ≒ What are the main parts of the system? ≒ Wheres the simple, big picture? [pause, blank looks] ≒ I have been here quite a few /mes Sheltering manager ≒ I need a vague idea of whats going on ≒ I need a warm fuzzy feeling that you know what youre doing
  • 3. Why do you need documenta/on? (2) ≒ Because you dont know what youre doing Some bits are clear but other bits are: fuzzier, older, broader, outside your domain, etc. I have been here quite a few /mes as well
  • 4. What documenta/on do you need? ≒ NOT 200-足page specs ≒ A clean, well understandable codebase with clear domain abstrac/ons 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 documenta/on of trickier bits like complex, infrequently needed con鍖g ≒ wiki is usually good for this
  • 5. Maps of your world (1) ≒ Tribal Maps Meaningful to the na/ves Or, more usefully, Fred met a dragon here once. It was de鍖nitely a dragon, not a /ger and he was able to get away by
  • 6. Maps of your world (2) ≒ Di鍖erent levels + di鍖erent info Contours, major towns, etc. ≒ In the so8ware world ≒ Simon Brown Context, Containers, Components, Classes ≒ For bigger or more complex systems, can split down into Viewpoints and Perspec/ves IEEE 1471 or Rozanski & Woods Especially if there are a lot of NFRs and/or lots of things outside the so8ware
  • 7. How does this work in prac/ce? (1) ≒ Choose a core, non-足vola/le subset If you cant decide on this then maybe you have more problems than a lack of lightweight docs Be selec/ve! S/ck them on the wall Keep them up to date (see Be selec/ve!) ≒ Otherwise let the code tell the detailed what and document the high-足level what and the why
  • 8. How does this work in prac/ce? (2) ≒ Environments o8en need aEen/on Maps of what talks to what in DEV, TST, STG, PRD If these docs are painful to maintain then maybe you should be automa/ng your environment builds
  • 9. How does this work in prac/ce? (3) ≒ Ask some ques/ons ≒ 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, dont leave it on a 鍖leshare to confuse people, throw it away 損Now!
  • 10. Dont forget At the end of the day Its all wri/ng (Pragma'c Programmers) Except when its drawing