lightweight documentation
TRANSCRIPT
Lightweight Documentation:An Agile ApproachDC Agile User Group meeting 11-Mar-2015
March 11, 2015
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
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 …
What could
possibly go wrong
with detailed
specification?
Introduction
“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
Why do we
document?
Valid reasons
Questionable
One principle
Communicate, communicate, communicate
Traditional SDLC Phases
• Definition
• Analysis
• Design
• Construction
• Test
• Transition and Migration
• Production
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
Who, What,
and Why?
Exercise
• 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?
Who, What, and Why?
Debrief
Traditional vs. Agile
• 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
• Traditional
– Project Plans
– Schedules
– Costs
– Resources
Planning
• Agile
– Product Vision
– Product Roadmap
– Releases
– Sprints
– Team Charter
– Individuals
• Core
• Peripheral
• 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
• Traditional
– Architecture
– System Overview
– Detailed Design
Design
• Agile
– Working Software
– Unit Tests
– Diagrams
– Repository/Wiki
• ReadMe
• Developer
Handbook
• Release Notes
• 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
Build a better
document
Exercise
• 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
Build a better document
Debrief
• Agile/Lean Documentation: Strategies for Agile Software Development,Scott W. Amblerhttp://www.agilemodeling.com/essays/agileDocumentation.htm
• Agile Technical Documentation,Jean-Luc Mazethttp://writersua.com/articles/Agile_doc/
• Writing User Documentation in an Agile Development Environment,Anne Gentlehttp://justwriteclick.com/2007/07/02/writing-end-user-documentation-in-an-agile-development-environment/
More Info
• 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