One of the values of the Agile manifesto is working software over comprehensive documentation. However many agile teams think that now we are Agile we don’t need to document. Come to this session to learn about lightweight documentation and how to strike a sensible balance between working software and documentation. Learn which documents are necessary and which documents you can do without as well. Learn about JIT lightweight alternatives to our tradition documentation set. Leave with specific techniques to evaluate the value of each document along with recommended alternatives.

1. Lightweight Documentation:
An Agile Approach
DC Scrum User Group (DCSUG) meeting 18-Aug-2014
August 19, 2014

2. • Excella Consulting for food, refreshments
and space
Thanks

3. Stephen Ritchie
◊ 20+ years of experience in software
development
◊ Focused on Agile since 2007
– Commercial software development
– .NET software engineering & Agile
principles
– Agile coaching & mentoring
◊ Organizer of the DC Alt.Net User Group
◊ stephen.ritchie@excella.com
◊ @ruthlesshelp

4. What could
possibly go wrong
with detailed
specification?
Introduction

5. “Documentation is not
anti-agile. If it were, then
there would not be any
agile books, articles, or
blogs.”
- Robert “Uncle Bob” Martin, 9-Mar-2006

6. Why do we
document?

7. Valid reasons
Questionable
One principle

8. Communicate, communicate, communicate

9. Traditional SDLC Phases
• Definition
• Analysis
• Design
• Construction
• Test
• Transition and Migration
• Production

10. Traditional SDLC Phases
• Definition => Detailed Project Plan
• Analysis => Detailed Specification
• Design => System Architecture
• Construction => Detailed Design Spec
• Test => Test Plans and Test Scripts
• Transition and Migration => Installation
Manuals
• Production => Operation Manuals

11. Who, What,
and Why?
Exercise

12. • In your group
• List of traditional SDLC documents.
• For each document
– Who is the audience(s) for the document?
– What is the reader looking for in the
document?
– Why does the reader want the document?
• In order to avoid something
• In order to have/obtain/achieve something
Who, What, and Why?

13. Who, What, and Why?
Debrief

14. Traditional vs. Agile

15. • Executable Specification (Gherkin)
• Document Stable Things (Final Concept)
• Generate System Docs (Rev. Engineer)
• Just Simple Enough (Not Too Simple)
• Display Information Publicly (Wiki)
• Purpose, Audience, Sufficiency
• Iterate, Iterate, Iterate
• Find A Better Communication Medium
• Start With Diagrams The Team Already Uses
Agile Docs: Best Practices

16. • Traditional
– Project Plans
– Schedules
– Costs
– Resources
Planning
• Agile
– Product Vision
– Product Roadmap
– Releases
– Sprints
– Team Charter
– Individuals
• Core
• Peripheral

17. • Traditional
– The System Shall
– Features
– Functional Specs
– Non-functional
– Screen Specs
– Rules
Requirements
• Agile
– Product Vision
– Product Roadmap
– User Stories
– Wireframes
– Style Guidelines
– Spec By Example
– Definition of Ready

18. • Traditional
– Architecture
– System Overview
– Detailed Design
Design
• Agile
– Working Software
– Unit Tests
– Diagrams
– Repository/Wiki
• ReadMe
• Developer
Handbook
• Release Notes

19. • Traditional
– Configuration Guide
– Installation
Instructions
– Administration
Guide
– User Manual
Support, Ops, and User
• Agile
– Working Software
• Installer
• Context Help
• User Experience
– Wiki
• ReadMe
• Release Notes

20. Build a better
document
Exercise

21. • In your group
• Iteration 1: Topic-Oriented Writing
– Using Post-It Notes Write 1 Topic
– Limit The Topic To 1 to 3 Words
• Review
• Iteration 2: Reader Stories
– As a (reader) … I want (content) … So that …
(I avoid something or I have something)
• Review
Build a better document

22. Build a better document
Debrief

23. • Agile/Lean Documentation: Strategies for Agile
Software Development,
Scott W. Ambler
http://www.agilemodeling.com/essays/agileDocumentati
on.htm
• Agile Technical Documentation,
Jean-Luc Mazet
http://writersua.com/articles/Agile_doc/
• Writing User Documentation in an Agile
Development Environment,
Anne Gentle
http://justwriteclick.com/2007/07/02/writing-end-user-
documentation-in-an-agile-development-environment/
More Info

24. • Let’s Go Around The Room
• One Idea
– Ways to improve the exercises
– Topics I should cover
– What could be done better next time
One More Thing

25. DC Software
Craftsman User
Group
(DCSCUG)
DC Scrum User
Group
Alt .NET
DC
International
Institute of
Business
Analysis (IIBA)
User Experience
Professionals
Association
(UXPA DC)
Agile Defense
Proponents Team
(ADAPT)
DC Continuous
Delivery Group
(DCCD)
Agile Leadership
Network
(ALN-DC)
django-district
DC Business
Intelligentsia
(DCBI)
Our Community
Excella founded or leads local IT organizations and Meetups. Join us for an
event!
Need space for your event?
Contact Us: info@excella.com

26. • .Net/C#, Python, Java, Ruby Developers
• Ux Designers
• ScrumMasters
• Agile Coaches
• IT Project Manager & Program Analyst
• Business Analysts (BA)
• Business Intelligence (BI)
Excella is Hiring

27. • Excella Upcoming Classes/Events
– CSM in College Park, MD
• 8/18 – 8/19
– Automated Acceptance Tests for BA
• 9/8 – 9/12
– Advance CSPO
• 9/15 – 9/16
– CSM
• 9/22 – 9/23
– Agile BI Training
• 10/7
– DC Business Analyst Development Day
• 10/10
User Group discount code, contact organizer
Training/Events

28. • AgileDC
– http://agiledc.org/
– 21 OCT 2014
Events

29. • DC Business Analyst Development Day (DCBADD) on
– Friday, October 10, 2014
– Westin Arlington Gateway​
• Conference will bring together Business Analysts, Project
Managers, and Agile Practitioners to learn valuable skills for
succeeding in an Agile environment. Topics will include:​
– Emotional intelligence​
– Change management​
– Agile requirements​
– Agile techniques in the Federal Government​
• Register - http://www.eventbrite.com/o/excella-
consulting-2232953017
Events