Thursday, November 22, 2007

Tales from the history of documentation, conclusion.

These tales are of course somewhat based on my own continuous battle for better documentation. The journey hasn't quite spanned that many years, but has instead crossed a number of different organizations with quality/configuration/project managers playing out the parts described in the previous tales.

These different kinds of managers often have a defining role in what kind of documentation should be produced in a project, even though they aren't actually involved in the production and especially the consumption of the documentation. The result is that the information exchange- and storage medias are not defined by the usability in the day-to-day work (by the common people), but instead is driven by theoretical quality and control concerns centered on a belief that every serious project must be build on a foundation of rock solid documentation.

It is easy for the people outside of the actual software production to fall into this trap. The documents produced by the development team is the only tangible product visible besides the actual software, which properly doesn't appear before the project has run for some time. And even when the software materializes, it is kind of magic, with strange things going on at the surface, produce by incomprehensible code woven by the developer.

The documentation becomes the managers sole media for defining and maintaining control of the development. After having started down this path most of the efforts to improve quality, efficiency and control will be channeled into 'improvements' to the documentation. The result usually lead to ever more documentation in increasingly complex structures. This again leads to decoupling of the software development and the formal documentation development.

If you don't recognize the described causes of 'documentation failure', try to look for the symptoms instead:
  • To much time is spend on documentation.
  • The relevant documentation does not exist.
  • It is very difficult to find documentation you haven't got hardcode links to.
  • The documentation isn't updated.
  • Documentation production, review, rework tasks 'block' application progress.
So if you have identified any of the above bullets as problems in your current project, please don't try to address these by increasing documentation control, amount, rules, etc. Instead try to base the solution on the primary cause for documentation, support for the common peoples needs.

No comments: