v1.0 how much documentation is useful documentation? sqnz, april 2013, wellington what level of...
TRANSCRIPT
v1.0
How Much Documentation Is Useful Documentation?
SQNZ, April 2013, Wellington
What level of documentation and when to produce it,is a hot topic in agile teams.
It should be a hot topic in all developments. How much shelf-ware do you write because it's "good practise"?
Who actually reads it critically and to what benefit? What could we do differently that would create greater engagement
in the same content? When is best?
© 2013 Smartmatix Ltd
v1.0
Which is you, in the spectrum of documentation?
2 / 11 © 2013 Smartmatix Ltd
Home grown;Typically No stds, overlap, bloatware; in places, too much and too little
RUP no tools;Limited definition, due to lack of tools;
XP
Explicitly no doc definition;Code docs only
ISO 12207 / DoD 498Clean precise definition of docs;Tailor / trim in method
RUP with tools; Strong definition
Scrum
Limited definition; no std in itself
Waterfall stages like PRINCE2
Method = 2-3 month cycles; can be 1 week!
Bi-week cycle
2-5 day cycle
v1.0
What do we need? Some points to consider
3 / 11 © 2013 Smartmatix Ltd
doc
Business Case
Close
doc
Maintain?Restore?
SLA?RFC?
Release?
The more you write the harder it is to changecode refactor
Templates are not forms to fill in …
v1.0 4 / 11
SR
What should it be? a tree of small artefacts
“Decompose”, “identify”, & don’t drown in detail …
Test
Artifacts
UseCase / User storyTest Strategy / Plan
Vision
HLDInterface Req. Spec’s
Code
Artifacts
© 2013 Smartmatix Ltd
v1.0 5 / 11
Why document? – validate & communicate
Problemdomain
UseCase
Design
Stake Holders(vision doc)
TestCasehierarchy
CodehierarchyReq. set
Interfacespecs
What is the UseCase of a car?
Where is component “make …”
© 2013 Smartmatix Ltd
v1.0
Documents to validate – but wait …
© 2013 Smartmatix Ltd
You call this Agile?
v1.0
Who actually reads it? Maintenance!
© 2013 Smartmatix Ltd
M S W
v1.0 8 / 11
What can we do? - what level and when?!
© 2013 Smartmatix Ltd
v1.0
What can we do? – stop writing; sketch
© 2013 Smartmatix Ltd 9 / 11
What’s the danger?!
v1.0 10 / 11 © 2012 Smartmatix Ltd
Manifesto for Agile Software Development
We are uncovering better ways of developingsoftware by doing it and helping others do it.Through this work we have come to value:
Individuals and interactions over processes and toolsWorking software over comprehensive documentationCustomer collaboration over contract negotiationResponding to change over following a plan
That is, while there is value in the items onthe right, we value the items on the left more.
http://agilemanifesto.org/
v1.0
Debating time
Food for thought re documentation & purpose:
► What’s good practice (ISO <-> XP)?
► What could we do differently that would create greater engagement?
► How to make / keep it agile?
► What information to keep? User Stories?
► What can we do with tools?
11 / 11 © 2013 Smartmatix Ltd
Smartmatix - Productivity tools and know-how for IT, projects & programs
v1.0
Appendix for eventualities
12 / 10 © 2013 Smartmatix Ltd
v1.0
Large 52 week project – 26 sprints
13 / 24 © 2012 Smartmatix Ltd
inception Elaboration Construction Transition
v1.0 14 / 24
Balancing specs and WBS – now robust
Use CaseDescript.
Vision
SRSIRS:UI / Report’s
Glossary
FPA:BasicERD-s
HLD
UseCase List
WBS = A deliverable oriented breakdown of work, anything on the WBS is in scope, anything not on it is out of scope. A WBS is NOT a task list
Validation!
System (is done)
Forum (is done)
Handle versions
CRUD books
CRUD tpls
News
Edit On-line
Upload
Manage collection
61 91 pages – 709 FP, 4 mths
© 2012 Smartmatix Ltd
v1.0© 2007 SmartMatix 15 / 39
What happens when things change?
Business Req.
UCs
TestPlan, cases, scripts
DevelopDesign, code, build
Exe
SRS
Vision
Software Spec.
… before long no quality!
Re-factor …
“Agile”“Planned”
v1.0
What can we do? - Right sizing
© 2012 Smartmatix Ltd 16 / 26