Making Global Teams Agile (part 3): Great Agile Documentation

As a follow up to the continuing conversation about making globally distributed teams work in agile fashion, we focus this article on what it really takes to make requirements documentation work. The most important step in getting this right is to recognize "this isn't your father's requirements document anymore" (although that might be his car commercial tag line) and that "requirements" are more than just a few words in a story. What all great agile requirements documents have in common is that they are short, to the point, focus on the visual, incorporate functional and technical guidance in one place, and they are expected to be iterative.

In part 2 we discussed using agile tracking tools like JIRA, VersionOne, and Pivotal Tracker along with a wiki to capture requirements. Wikis are great for requirements from one perspective because they are easy to author, quick to edit, and track versions over time (which is invaluable) in understanding change. Every day that goes by on an agile project, people have questions about how and what to develop to meet the needs of the customer. Capturing those answers as you go and making sure that where the customer and technical leads expect consistency, there is clear guidance the team can always get to means the difference between success and failure. Surprisingly little effort (as a start) just putting together a simple wiki page for each area of your project and keeping it up to date incrementally makes an enormous difference and saves tons of time and mistakes.

While Wikis do a great job of tracking change over time and they are more consolidated (often) than your stories (sometimes you'll see 20 or more stories for one functional area of your project) they have 2 major shortcomings: they still spread work out in many places and they are not disconnected. Sometimes, it is just plain easier to use a real document or tool to share details. Case tools like VP-UML and Poseidon (I site these for their platform independence) are great for sharing technical intent across a distributed team and the ability to share documents like database diagrams, class diagrams, and sequence diagrams (these are some of the most useful visualizations for communicating technical direction) can save hours or even days of re-work. Throwing implementation guidelines, a handful of visualizations, and requirements together for the shared standards and a couple functional areas of the project into a single, portable word document (as an example) can also be extremely helpful for allowing developers to work disconnected and stay on target. Whichever document types your team uses, they should be treated just like code and should be checked in and shared via your source code repository (probably GIT or SVN these days) or at the very least uploaded to the wiki in an appropriate location. Again, these documents are works in progress and their content may get moved onto or pulled from the wiki as appropriate to the needs of the team.

Focusing on the visual in these documents is another important way you can set the team up to succeed. Basic wire-frames or designs of interfaces are the first place to start. From there, descriptions of data in the form of an annotated ERD diagram and a basic class and package diagram ensure that the team understands what is expected for delivery, what information is involved, and how the technical lead and team agree the basic structure should be implemented. For projects using scripting languages like Ruby and PHP, you can still use component diagrams to communicate this. What is great to realize is that a project with 100 functional features probably only requires 10 - 12 of these pictures in place for the team to infer how everything should work, and you can build these in just a couple of hours / week and save hours and hours of miscues and confusion in every sprint. If you're skeptical, try doing a search through your inbox for one of your story names and see how many e-mails got traded over the course of a single sprint and then try spending the time on docs and repeat the exercise.

Back in the days of Waterfall and the Rational Unified Process (RUP) the software architecture community pushed a very formal methodology for doing analysis and design that often led (and still does sometimes today) to 2 or 3 separate and specific documents for a project. These documents became rigid and required layers of change management to alter and a repeat of the entire waterfall process. Agile documents still benefit from structure, but it is far better to merge scope, functional requirements, and technical guidance into one iterative document (or at least one per area). The skills of a great analyst, architect, development lead are still incredibly valuable and applicable to agile or SCRUM projects, but now they work as a team to produce the exact amount of guidance needed at any given time. The easier this information is to access and have at the developer's fingertips, the better, and the clearer the authoritative source of the latest ideas are, the less time the team wastes in confusion and re-work. It shouldn't be un-common to see a 4 page document that shows 2 use cases, some functional requirements, a wireframe, a class diagram, and a database diagram mixed together. You'll find lots of this content and concepts are re-usable from story to story and function to function and if you commit to iterating you produce great guidance that keeps the team moving as one to get the job done with minimal week to week effort.

As we said, this is not your father's documentation but a few hours / week spent doing this out ahead of the project team can double your team's velocity and effectiveness easily. The trick is right-sizing and simplifying the documentation to your team's needs, establishing templates and patterns that make producing and reading these documents easy, keeping the documents in some kind of version management system and easily accessible to everyone (online and offline), and accepting the iterative nature of the documents and the process. The goals are to save time and create shared vision to improve execution. In the end, team synergy and communication accounts for more than half of the team's effectiveness and a great documentation process can make it look easy.