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 Smart m atix Ltd

v1.0 Which is you, in the spectrum of documentation? 2 / 11 © 2013 Smart m atix 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 / DoD 498 Clean 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 Smart m atix Ltd doc Business Case Close doc Maintain? Restore? SLA? RFC? Release? The more you write the harder it is to change coderefactor 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 story Test Strategy / Plan Vision HLD Interface Req. Spec’s Code Artifacts © 2013 Smart m atix Ltd

v1.0 5 / 11 Why document? – validate & communicate Problem domain UseCase Design Stake Holders (vision doc) TestCase hierarchy Code hierarchy Req. set Interface specs What is the UseCase of a car? Where is component “make …” © 2013 Smart m atix Ltd

v1.0 Documents to validate – but wait … © 2013 Smart m atix Ltd You call this Agile?

v1.0 Who actually reads it? Maintenance! © 2013 Smart m atix Ltd M S W

v1.0 8 / 11 What can we do? - what level and when?! © 2013 Smart m atix Ltd

v1.0 What can we do? – stop writing; sketch © 2013 Smart m atix Ltd 9 / 11 What’s the danger?!

v / 11 © 2012 Smart m atix Ltd Manifesto for Agile Software Development We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value: Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan That is, while there is value in the items on the right, we value the items on the left more.

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 Smart m atix Ltd Smart m atix - Productivity tools and know-how for IT, projects & programs

v1.0 Appendix for eventualities 12 / 10 © 2013 Smart m atix Ltd

v1.0 Large 52 week project – 26 sprints 13 / 24 © 2012 Smart m atix Ltd inceptionElaborationConstructionTransition

v / 24 Balancing specs and WBS – now robust Use Case Descript. Vision SRS IRS: UI / Report’s Glossary FPA: Basic ERD-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 Smart m atix Ltd

v1.0 © 2007 SmartMatix 15 / 39 What happens when things change? Business Req. UCs Test Plan, cases, scripts Develop Design, code, build Exe SRS Vision Software Spec. … before long no quality! Re-factor … “Agile”“Planned”

v1.0 What can we do? - Right sizing © 2012 Smart m atix Ltd 16 / 26