Design

Agile Documentation Strategies

Documentation is an important part of every system, agile or otherwise.

A Few Myths and Misconceptions

To understand the agile approach to documentation, you must first understand the potential misunderstandings about documentation that have seeped into traditional thinking:

• Documentation isn't the primary issuecommunication is. For example, your primary goal isn't to document requirements, it's to understand them so that you can implement them fully. Your primary goal isn't to document the architecture, it's to formulate a viable one that meets the long-term needs of your stakeholders. This isn't to say that you won't decide to invest in such documentation, but that isn't the raison d'tre for your project.

• Comprehensive documentation does not ensure project success. Just because you have a detailed requirements specification that has been reviewed and signed off, that doesn't mean that the development team will read it, or if they do, that they will understand it, or if they do, that they will choose to work to the specification. Even when the "right thing" happens, comprehensive documentation still puts the project at risk because of the perceived need to keep the documentation up-to-date and consistent. Your real goal should be to create just enough documentation for the situation at hand; more on this later.

• Documentation doesn't need to be perfect. People are flexible, they don't need perfect documentation. Furthermore, no matter how hard you work, it's very unlikely that you could create perfect documentationeven if you could, it isn't guaranteed that the readers will understand it anyway.

• Few people actually want comprehensive documentation. When was the last time you met a maintenance programmer who trusted the system documentation that they were provided? Or an end-user who wanted to sit down and pore over a massive user manual? What people typically want is well-written, concise documentation describing a high-quality system, so why not invest your time to deliver that instead?

• Documentation doesn't need to be standardized. Many organizations have adopted the unfortunate philosophy that repeatable processes lead to success, yet in reality what you really want is repeatable results (that is, the delivery of a high-quality system). The quest for repeatability often leads to templates, and because each system has its own unique set of issues, these templates have a tendency to grow over time into all inclusive monstrosities that do little more than justify bureaucracy. Try to achieve a reasonable level of consistency, but don't go overboard doing so.

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!