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.
