Lightweight Documentation

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