Where is the Documentation?

In the simplified software engineering process model there are 10 phases. These are: problem, requirements engineering, requirements specification, design, technical specification, implementation, coding, testing, system integration/deployment, and maintenance. No wonder then, that there are no good documents for software projects. Help documents, user manuals, deployment guides, and other useful texts often expected from software and rarely included aren't even part of the basic model of development. Testing gets short shrift in most projects, and unfortunately documentation gets even shorter shrift.

Documentation is often left as the final stage of software development, and rightfully so. It is difficult to write documentation for a project before it is complete. You can't write help about features that aren't implemented or about screens that could change. Having incorrect documentation is almost worse than no documentation at all.

In today's hyper "extreme" software development environments, software is constantly evolving. Daily builds, iterative development, functional prototyping, and other "rapid" delivery methods mean that software projects grow and evolve on a daily, if not hourly basis. With such a shifting landscape it becomes impossible to provide good documentation. Documenting code might be possible, but providing documentation for end users is a nightmare. No project wants to slow down the roll out of the latest build just so that documentation can be completed.

Unfortunately this means that end users are often left to fend for themselves. This has given rise to the numerous "self serve" forums and user sites that populate much of the web. When no documentation exists, internet search engines become the documentation. This isn't only limited to open source software, many commercial software projects refer customers to their online "knowledge base" which is often populated mostly by end users. Imagine, paying for a piece of software, then having to write the documentation yourself!

The mark of true quality is the last 10%. This shows in most software. The rough edges aren't just an artifact of bleeding edge development, they're a sign of poor quality. End user documentation is often left until the last minute and then swept under the rug in the rush to release the latest and greatest tool. Unfortunately this hurts the adoption of your software product. Unless the stellar user interface is so intuitive or the need for the software is so great that users can figure it out on their own, or are forced to, you may just lose potential users. It pays to build in time for documentation. It makes your project friendly, and higher quality.