4 years, 10 months ago

Documentation

Link: http://www.etc-architect.com/?p=295

The first thought on documentation is that it is boring, but somehow necessary. And just this is the start of the downfall as documentation for documentation sake is a bad idea and usually helps no one. The really important part of documentation is about sharing information and the really difficult part of information sharing is to make information read. You will see there is lot of intelligent and really good information on architecture accessible, which very few people will ever read. Most things I write only a few will ever read and at least a quarter no one will read.

So how can we make documentation to be read? Actually it dependents on what you are documenting. If it is a design visualisation is key, if it is an old idea a picture is the best way with only a bit of test, but if it is a new idea pictures are bad. If you want to document something technical a wiki may be a good thing (as long as you use one that people will use, not the one that is most IT interesting). So there is no ideal format for documentation, but since we as architects always have the tendency to standardize everything the documentation we usually created will even in the best case be sub-optimal.

So if you next time start with documentation you might want to ask yourself what type of format will motivate others to consume the output rather than just to use the standard Word or PowerPoint template.

Related Post