1.
Lightweight Documentation:
An Agile Approach
DC Agile User Group meeting 11-Mar-2015
March 11, 2015

2.
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

3.
Lightweight Docs
How can you help Agile teams get
better at delivering documentation?
As a ScrumMaster …
As an analyst …
As a coder …
As a tester …
As a product owner …

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
• Given a traditional SDLC 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