Meeting Strict Documentation Requirements in Agile

AW16
Agile Development Concurrent Session
11/12/2014 4:15 PM
"Meeting Strict Documentation
Requirements in Agile"
Presented by:
Craeg Strong
Savant Financial Technologies, Inc.
Brought to you by:
340 Corporate Way, Suite 300, Orange Park, FL 32073
888-268-8770 ∙ 904-278-0524 ∙ sqeinfo@sqe.com ∙ www.sqe.com

With twenty-five years of experience in information
technology, Craeg Strong is the technical lead of the FBI CODIS
project, shepherding its transition from waterfall to agile. Craeg
started with Project Athena during his undergraduate studies at MIT
and now owns a small consulting business based in New York City
and Washington DC. An experienced turnaround artist, Craeg has
successfully instituted agile practices in some of the largest and
most complex commercial and government software projects. His
areas of expertise are as a hands-on software architect and agile
coach. Craeg is a Certified ScrumMaster, PMP, and contributor to
the Apache Ant open source automated build tool.

Craeg Strong
CTO, Ariel Partners
November 21, 2014
Orlando, FL
© Copyright Ariel Partners 2014 sales@arielpartners.com (646) 467-7394
Best Practices for
Lean Documentation
How an Agile team can meet
documentation requirements
without losing sleep

Software Development since 1988
Large Commercial & Government Projects
Turned Around Projects With Agile
Apache Ant Open-Source Contributor
New York & Washington DC Area
CTO, Ariel Partners
CSM, CSP, CSD, CSPO, PSM,
PMI-ACP, PMP
www.arielpartners.com
cstrong@arielpartners.com
@ckstrong1
Craeg Strong

Agenda
1. Context
2. Contrasting Approaches Regarding Documentation
3. An Agile Strategy for Documentation
4. Example Document Update Process
5. Typical Full-Lifecycle Documentation Set
6. Specific Approaches & Recommendations

Context
Heavily Regulated Industries
Insurance
Health Care
Pharmaceuticals
Mission-Critical/Life-Critical Systems
Military
Criminal Justice
Financial Services
Transportation
Energy
Local, State, Federal Government

Different Attitudes Regarding
Documentation
Traditional Governance
Comprehensive documentation is a critical
component of software development
Agile
Working software over comprehensive
documentation

Different World Views
1. Standardize
and Document
Processes
2. Measure and
Control within
Tolerances
3. Streamline
Processes
Level 1
Initial
Level 2
Managed
Level 3
Defined
Level 4
Quantitatively
Managed
Level 5
Optimizing
 Significant Up-Front
Planning
 Heavy Emphasis on
Documentation
 Begin With Lean, Efficient Processes
 Automate Processes
 Minimal “Right Sized” Documentation

Why Is This A Problem?
OK, so we have to produce documentation. We add documents to our Backlog.
Why is this a problem?
Heavy Documentation Requirements
Government or Corporate Standards
Regulatory Requirements
SOX, HIPPA, NAIC, FDA, SEC
Volume
IV&V Teams – Their job is to find problems
Documents receive much more scrutiny
Skill Mismatch: most IT professionals are not writers
Difficulty

Agile Strategy For Documentation
1. Improve Documentation Capabilities
2. Plan and Measure the Work
3. Reduce Amount of Documentation Required
4. Reduce Effort Required to Produce Documentation

Adapting to Complexity:
Additional Project Roles
 New Project
 Lightweight Governance
 Little Technical Debt
Traditional Scrum Team
Developers Testers Business
Analyst
CM/Build
Engineer
DBA
 Legacy Project
 Heavyweight Governance
 Significant Technical Debt
Documentation And Reporting
Report
Developer
UX
Designer
Technical
Writer
Development
Developers Testers Business
Analyst
CM/Build
Engineer
DBA
Increasing Complexity

Documentation Tools
Custom Metrics and Reports
Project Portal / Wiki
Publish
PowerShell Script
TFS
Tasks
Test Results
Features
Content Management System
Vendor Provided Metrics and
Reports

Adapting To Complexity:
Tracking Documentation Work
 New Project
 Lightweight Governance
 Little Technical Debt
Technical
User Story
Test Automation Frameworks,
Custom Scrum Templates,
Large Code Refactorings
Development Tasks
Technical Tasks
Testing Tasks
Documentation Tasks
User Story
 Legacy Project
 Heavyweight Governance
 Significant Technical Debt
Business
User Story
Usability Improvements,
New Features
Documentation
User Story
Design Documents,
On-Line Help, CBT
Increasing Complexity

Tracking Documentation Effort
Doc
User
Story
Update
Content
Peer
Review
QA Delivery
Biz
User
Story
Update
Design
Docs
Update
Training
Materials
Coding Testing
Peer
Review
Tech
User
Story
Coding Testing
Peer
Review
Update
Install
Guide
#3 – Assigned to cstrong
Address Rework for User Guide
[TB: 4h]
March 8, 2014
Documentation
Re-work Tracked
As Defect
Related To
Documentation

Technical Documentation Example
Sprint 1 Sprint 2 Sprint 3 Sprint 4
Release
New
Feature
New
Feature
New
Feature
Update
Design
Doc A
Update
Design
Doc B
Bug
Fix
New
Feature
Update
Design
Doc B
Update
Design
Doc A
Sprint
Document
Contents
Release
Document
Delivery
Definition
Of Done
Doc
Doc
Deliver
Design
Doc A
Deliver
Design
Doc B
Doc
Deliver
Release
Notes

Documentation Metrics
24%
32%
44%
Documentation
Technical Features
Business Features
141
49%
76
26%
23
8%
11
4%
37
13%
Delivered On Time
Delivered < 10 Days Late
Delivered 10-20 Days Late
Delivered 21-29 Days Late
Delivered ≥ 30 Days Late
0
5
10
15
20
25
30
Jan Feb Mar Apr
3 or more 2nd Rework Rework Accepted

Reducing Number of Documents
To Be Maintained
Single Source for Content
User GuideOnline Help
Generate Detailed Design
SCM
Manual Installation Guide 
Automated Installer

Reducing Effort Required To Maintain
Documentation
Alternative Media:
Video, Wiki
Customize & Streamline
Document Templates
Document “To Be” Design 
Document “As Is” Design

Agile Strategy For Documentation
1. Improve Documentation
Capabilities
 Add Technical Writer to the team
 CMS tools
 Automation tools
2. Plan and Measure the work
 Add Documents to the Backlog
 Track Time Spent
 Track Documentation-related
work vs. software development
3. Reduce Amount of
Documentation Required
 Employ Automation To Generate
Documentation
 Single source content and generate
multiple representations
 Remove Need For Documentation by
automating manual steps (e.g.
automated install)
4. Reduce Effort Required to
Produce Documentation
 Customize and Streamline Document
Templates
 Focus on as-is rather than to-be
 Explore Alternative Media: Wiki, Video

Agile Documentation Process
1. Documentation
Tasks Captured In
Backlog
4. Technical Writer
Performs QA
Tech Writer Document Checklist
 Header
 Glossary
 Grammar
 …
3. Technical Peer
Review
Developer B
Technical Content
 Accuracy
 Completeness
6. Delivery Manager
Announces Delivery
To Customer
Delivery Manager
Delivery Email
2. Developer
Updates Content
Developer A
 Track Changes: ON
DRAFT
5. Delivery
Manager
Prepares Delivery
Delivery Manager
 Accept Changes
DELIVERABLE

Typical Full-Lifecycle
Documentation Set
Planning
 Project Vision
 Concept of Operations
 Project Plan
 Earned Value Management
Management
 Management Plans
 Meeting Minutes
 Monthly Program Reviews
Technical
 Requirements Specifications
 Functional Specifications
 Component Design
 System Architecture
Testing
 Test Plans
 Test Reports
Installation
 Release Notes
 Version Description Document
 Installation Guide
End User
 User Guide
 Online Help
Training
 Instructor Led Training
 Computer Based Training

Management Plans (PMBOK)
Traditional
 Project Management Plan
 Risk Management Plan
 Communication Plan
 Quality Assurance Plan
 Configuration Management Plan
 Security Management Plan
 (others?) Agile Strategy: Eliminate or Reduce
 Required By CMMI or Governance?
 Keep It Very High Level
 Minimal Maintenance Required
 Streamline Templates Where Possible
 “Borrow” language from standard sources

Planning Documents
Traditional
 Product Vision Document
 Resource-Loaded Schedule
 Gantt Chart
 Earned Value Management
Agile
 Product Vision Document
 Product Roadmap
 Product Backlog
 Release Burndown
 Team Charter

Technical Documents
Agile
 User Stories
 Annotated GUI Mockups
 Streamlined Architecture
 Streamlined Design Docs
Traditional
 “Shall” Requirements
 Functional Specifications
 Architecture Specification
 Software Design Docs

Example: Streamlined Design Document
TRADITIONAL
To-Be
“Tick The Box”
o Fill In The Template
o Applicable? Maybe.
o More Is Better
Lots of Details
o Long API Listings
o Busy Complex Diagrams
o Every Process Step In Detail
AGILE
As-Is
As Simple As Possible (But No Simpler)
 Its All About Context
 History And Background
 Trade-offs and Design Decisions
Explain Why. Give Examples
 High-Level Architecture
 How Do Pieces Fit Together
 Pitfalls, Best Practices
 Reduce Program Risk
 Government: Every Five Years Team
Disbands, Mission Continues
Why
Document
Design
in Agile?

Reporting
Traditional
 Requirements Specification
 Requirements Traceability
Matrix (RTM)
 EVM Reporting
Agile
 Feature Specifications
 “Agile RTM”
 Sprint Burndown
 Automated Testing Reports

Example: Behavior-Driven
Development (BDD)
 Documents System Features
 By Creating Tests That Fail Unless The Features
Are Implemented Correctly
 Test Specifications Can Be Exported To Create
“Living Documentation”
User
Story
#53
Acceptance Criterion 1
Automated Acceptance Test #53.1
Given a claim has been reported…
When the claim is entered…
Then the system should return…
Also Known as Acceptance Test Driven Development (ATDD)

Generating Documentation From
Specifications
 Pickles Report Generator
 Features organized In tree structure
 More sophisticated commercial options
available (SpecFlow+)

The Agile RTM
 All system functions expressed as user stories
 All user stories have acceptance criteria
 Each criterion translated to an automated test using structured English
(Gherkin)
 Customized report matches epics and user stories to automated
acceptance tests
 Test fails unless software is implemented correctly
Links to Theme
Record in TFS
Links to Epic
Record in TFS
Links to User
Story in TFS
Links to Feature
Documentation
Generated via Pickles

Generating the Agile RTM
TFS Build
PowerShell Script
TFS
Themes, Epics,
User Stories
Console Runner
Results of
Automated Tests
PicklesDoc
Document Generation
Specifications
Agile RTM Project Portal / WikiCombine & Transform
XML Files
Publish

Testing Documentation
Traditional
 System Test Plan
 System Test Report
 Performance Test Plan
 Performance Test Report
Agile Strategy: Generate & Streamline
 Required By CMMI or Governance?
 Minimal Manual Intro + Generated Appendix
 Generated From Automated Tests
 Exported From Manual Testing Tool
(e.g. Microsoft Test Manager)

End User Documentation
Traditional
 Installation Guide
 Release Notes
 User Guide
 Online Help
 Computer Based Training
Agile Strategy: Eliminate, Consolidate, Replace
 Automated Installation
 Generate User Guide & Online Help From
Single Source
 Videos of Training Classes Reduce Need for
Extensive User Guide & Computer Based
Training

Summary
1. There Is No Silver Bullet For Documentation
2. Different Strategies
 Reduce
 Replace
 Generate
 Consolidate
 Eliminate
3. Additional Roles & Tools Needed
4. Significant Customization Likely Required
5. Achieving Optimal Automation Costly & Time-Consuming
6. Expectation Management Critical to Success
Mission Critical Programs Can Adopt Agile…
…And Still Produce High Quality Documentation

• Agile/Lean Documentation: Strategies for Agile Software
Development,
Scott W. Ambler
http://www.agilemodeling.com/essays/agileDocumentation.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/
• CMM or Agile: Why Not Embrace Both!
HillelGlazer, Jeff Dalton, David J. Anderson, Michael Konrad, Sandra
Shrum
http://resources.sei.cmu.edu/library/asset-view.cfm?assetid=8533/
More Info

Questions?

Meeting Strict Documentation Requirements in Agile

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Meeting Strict Documentation Requirements in Agile

Similar to Meeting Strict Documentation Requirements in Agile (20)

More from TechWell

More from TechWell (20)

Recently uploaded

Recently uploaded (20)

Meeting Strict Documentation Requirements in Agile