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 ∙ [email protected] ∙ www.sqe.com

mailto:[email protected]

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 [email protected] (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 [email protected]

@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

DeliverDesign Doc A

DeliverDesign 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 Guide

Online 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



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 Concept of Operations User Stories Annotated GUI Mockups Streamlined Architecture Streamlined Design Docs

Traditional Concept of Operations “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+) © Copyright Ariel Partners 2014 [email protected] (646) 467-7394

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 / Wiki Combine & 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

EXHIBIT A: DOCUMENTATION LIST

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

http://www.agilemodeling.com/essays/agileDocumentation.htm

http://writersua.com/articles/Agile_doc/

http://justwriteclick.com/2007/07/02/writing-end-user-documentation-in-an-agile-development-environment/



Questions?


meeting strict documentation requirements in agile

Software

lean documentation

fl copyright ariel partners

ariel partners csm

agile practices

agile team

agile coach

agile working software

agile strategy