The Art of Agile Product Documentation

A Workshop Facilitation Guide

This sense-making workshop helps teach a team how to simplify valuable documentation and reduce wasteful documentation.

Myth: "Agile teams don't document."

Truth: Agile teams produce excellent and valuable documentation.

Agile Engineering practices have revolutionized the ways in which documentation is treated and produced. In high-stakes environments with heavy compliance and audit requirements, a tendency toward exhaustive documentation is dangerously common. This workshop provides direct guidance and simple tools to help a document-heavy workplace think differently about documentation.

I developed this workshop to help an organization reframe their understanding of documentation with respect to knowledge work in complex environments so that they may eliminate unnecessary artifacts and simplify/automate others.

Downloads

• Facilitator’s Guide (HTML below)
• Facilitator’s Guide DOCX
• Facilitator’s Presentation PPTX
• Canvas & Print Materials: Cards, Quadrant labels, Canvas

How to Use

1. Download the materials above.
2. Conduct the workshop with your own teams & stakeholders.
3. Tell me how it goes via Twitter or LinkedIn.
4. Ask questions or suggest changes. Scroll to bottom of this page to leave a comment or question.

Purpose & Summary

• Reframe our understanding of documentation with respect to knowledge work in complex environments. (Documents are not truth. They are snapshots of current understanding. If not treated carefully, they create fiction not transparency.)

• Reframe our understanding of 'implementation' — when does it occur in product development? (Hints: it isn't a phase or project milestone; it is every moment in which a decision is codified in the product.)

• Compare the purpose of artifacts/documents produce pre and post implementation. (Documents pre-implementation do not represent decisions; they represent, at best, incomplete information. Documents create at or after the point of implementation are obsolete the moment they are produced.)

• Appraise commonly-used documents with respect to customer-value — in contrast to perceived business/process 'importance'. (Documents are often produced because someone demanded they be done; but many documents are not the artifacts that any customer is willing to pay for. How might we focus on documentation which has actual value?)

• Consider and describe ways each artifact may be eliminated or simplified. (Like eliminating a Business Requirements Document in favour of a flexible/dynamic Product Backlog, how might an Agile team simplify the design and production of necessary artifacts/documents?)

Learning Objectives

Attendees will:

• Reframe their understanding of documentation with respect to knowledge work in complex environments. (Documents are not truth. They are snapshots of current understanding. If not treated carefully, they create fiction not transparency.)

• Reframe their understanding of 'implementation' — when does it occur in product development? (Hints: it isn't a phase or project milestone; it is every moment in which a decision is codified in the product.)

• Compare the purpose of artifacts/documents produce pre and post implementation. (Documents pre-implementation do not represent decisions; they represent, at best, incomplete information. Documents create at or after the point of implementation are obsolete the moment they are produced.)

• Appraise commonly-used documents with respect to customer-value -- in contrast to perceived business/process 'importance'. (Documents are often produced because someone demanded they be done; but many documents are not the artifacts that any customer is willing to pay for. How might we focus on documentation which has actual value?)

• Consider and describe ways each artifact may be eliminated or simplified. (Like eliminating a Business Requirements Document in favour of a flexible/dynamic Product Backlog, how might an Agile team simplify the design and production of necessary artifacts/documents.)

Session Timebox

• Minimum (recommended): 45 minutes
• Maximum (recommended): 75 minutes

Target Audience

Intermediate to Advanced. This session is designed for a broad audience including auditors, managers, agile team members and their stakeholders.

I have facilitated this workshop with single teams and with large groups (~85). It parallelizes nicely and could be done, theoretically, with an infinite number of table-groups of between 3 and 9 people.