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.

Tales from the history of documentation, chapter three

Years came and went and before long the concerns regarding the safety of the computer based documents where addressed. Safe archival systems where created, structures for storing the documents where defined, procedures for when and how to change the documents were made, elaborate software tools for controlling all the defined rules were implemented, template repositories where established to ensure standards for the documents where followed etc.

But the common people didn't use the formal computer based documentation frameworks that much. The complexity of it all was a bit overwhelming, and if you did manage to find something in the huge folder structures, it was properly out of date or wasn't really relevant for the common peoples daily life's.

To improve on this inability of the common people to embrace the electronic documents, documentation support roles were created, more documents were written on how to handle the other documents, people where sent on courses to learn the 'right way', rewards were given to the ones succumbing to the correct document usage, all to ensure that the common people where 'fixed' and finally brought to understand, what was in their best interest.

But even with this massive effort to perfect the documentation system, the common people didn't really use it much. They still preferred to use easier channels of information, which didn't have the complexity of the official documentation system.

Then one day a young enthusiastic fellow approached the community with a new media for communication and maintaining information. A new web based media, where everybody could easily find information and contribute to the documentation if they felt like it, he called it a wiki. He said that the wiki was a major improvement over the conventional document based ways of maintaining information. Information on the wiki was much easier to use, nothing was more than a mouse click or a text search away, and it was much easier kept up-to-date because the modification of the wiki was so easy and everything was changed directly in the central repository.

The experts and managers from the document organization listened to the young man and told him this wiki thing looked very nifty and he was very welcome to use it, but it could of course not be used for the more important information. After all, it wasn't possible to control who changed the documentation, who read the documentation, the documentation was difficult to print on real paper documents. In fact it didn't look at all like real documentation should, it was just a mess of information thrown together by people who didn't understand the finer art of document management.

And of course the primary goal of documents was the ability to store the documentation. When this had been perfected, you could look at the accessibility of the documents. And this issue had already been addressed though the previous efforts to guide the common people towards better understanding of the 'science of documents'.

The young man was pretty disillusioned by this lack of vision from the documentation experts and managers, but agreed to follow the decision to only use the wiki for things considered less important by the experts.

The years passed, and surprisingly enough wikis gradually started to replace the document based structures. Apparently the intangible concept of 'easy to use' and the possibility of everybody to contribute was found to be 'better' by the common people.

And this is where we stand today.

The End.

Tales from the history of documentation, chapter two

Generations came and went and before long many of the more long term issues regarding storing information had been addressed. Storage facilities (archives) had been established at central places, so the documentation could be kept for many, many years and review boards controlled any updates to the archives to ensure the quality of the documentation was maintained.

But the common people didn't use the huge archives that much. The complexity of it all was a bit overwhelming, and if you did manage to find something, it was properly out of date or wasn't really relevant for the common peoples daily life's.

So in an attempt to remedy this, procedures were carefully written on how to ensure updated and relevant documentation. Elaborate indexes were also created to document how to find the documentation. And all this was of course also stored in the archives, because this was the right place to keep important information.

To assist in facilitating the efficient proliferation of the documentation archival management system, an organization of archival and process experts was created with the responsibility of guiding people towards the information they needed. A host of managers was also need to ensure everything was handled correctly.

But even with this massive effort to perfect the documentation system, the common people didn't really use it much. They preferred to use more informal channels of information, which didn't have the complexity of the official documentation system.

Then one day a young enthusiastic fellow approached the community with a new media for maintaining documentation. A new electronic device called a computer was able to provide electronic versions of the document spreadsheets and other forms of paper documentation stored in the archives. He said that the computer was a major improvement over paper-based documentation. The electronic documents where much easier to edit and maintain. They could also be kept in computer based storage systems, avoiding the huge paper document archives. Copy and distribution was also much easier, just a click of a button.

The experts and managers from the archives listened to the young man and told him this computer thing looked very nifty and he was very welcome to use it, but it could of course not be used for the more important information. After all, it wasn't as safe as paper, it could loose power, the data could be corrupted or hacked, incompatibility issues would certainly arise. The control of the documentation would also be difficult to enforce, when copying and distribution was so easy.

The young man was pretty disillusioned by this lack of vision from the archive experts and managers, but agreed to follow the decision to only use the computer for things considered less important by the experts.

The years passed, and surprisingly enough computers gradually started to replace the paper documents. Apparently the intangible concept of 'easy to use' and the possibility of everybody to contribute was found to be 'better' by the common people. Soon most documentation was stored on computers and the archives were used more for historic documentation.

End of chapter two

Tales from the history of documentation, chapter one

One of the main battles I have been fighting during the years, is the fight against inefficient documentation. Inspired by these challenges I would like to tell a tale of the epic documentation struggle through the ages.

Once upon a time important information was stored by carving runes it into huge stones. This way of maintaining information was thought to work very well by the elders. It had worked for many generations, the documents would last for many, many years, the rune stones never moved, so the information should be easy to find and it was ensured that only the wise elders was allowed to contribute to the documentation.

But for some reason the writing on the stones weren't used that much by the common people, they mostly preferred to talk to other people with the relevant knowledge or just write notes in the dirt. When the common people were asked why they didn't use the stones, they answered, that it took too long to go to the stones and read the information and the information written there was out-of-date and wasn't really relevant for the common people.

The elders response to this was that the common people needed more teaching on how to use the rune stones and more rules regarding rune usage should be developed (and of course written on other rune stones). Another improvement would be the manufacture of even more stones to close the holes in the existing information and more effort should be put into updating the rune stones.

People were sent on rune stone courses, massive amounts of rune stones were produced, but the usage of the rune stones didn't improve much.

Then one day a young enthusiastic fellow approached the community with a new media for maintaining documentation. It just consisted of thin sheets of wood (he called it paper) and you could just write on it with small pieces of charcoal. He said that the paper was a major improvement to the rune stones, the paper was much 'easier' to used than the rune stones, everybody could contribute to the documentation, you could easily update the writing on the paper and you could bring the relevant documentation with you to use it where you needed it.

The elders listen to the young man and told him this paper thing looked very nifty and he was very welcome to use it, but it could of course not be used for the more important information. After all, it wasn't as safe as rune stone, it could burn, rot, bleach or blow away. Anybody could write on paper, which would be dangerous, who would control the changes. It would also be impossible to maintain the archives the rune stones provided, when everybody could just pick up a document and take it with him.

The young man was pretty disillusioned by this lack of vision from the elders, but agreed to follow the elders decision to only use the paper for things considered less important by the elders.

The years passed, and surprisingly enough paper gradually started to replace the rune stones. Apparently the intangible concept of 'easy to use' and the possibility of everybody to contribute was found to be 'better' by the common people. Soon all documentation was stored on paper and the rune stones retired to museums and parks.

End of chapter one