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 …
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
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?
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
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
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
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