Friday, January 28, 2011
Enterprise Architecture: Documentation 2.0
A lot of our problems with documentation come from the significance we invest in it. Culturally speaking, we tend to believe what is written down somehow must have more truth than something learned through other means...
Last year I asked the question: Is it possible to create too much documentation? Now I am asking whether one should even bother reading existing documentation.
Is it wise for an otherwise logical group of IT professionals to believe in something that they know is almost never true? What if we simply started with a simple guide as to what documentation is used for and more importantly what doesn't have fiscal return in documenting (If you have documentation in a contract, you are already a loser).
Have you heard of McGovern's law of documentation which states: The likelihood of keeping all or part of a software artifact consistent with any corresponding text that describes it, is inversely proportional to the square of the cognitive distance between them. For those who like things more simple, this translates into out of sight, out of mind....
| | View blog reactionsLast year I asked the question: Is it possible to create too much documentation? Now I am asking whether one should even bother reading existing documentation.
Is it wise for an otherwise logical group of IT professionals to believe in something that they know is almost never true? What if we simply started with a simple guide as to what documentation is used for and more importantly what doesn't have fiscal return in documenting (If you have documentation in a contract, you are already a loser).
- All documentation is to be distrusted as out of data and subjectively biased
- Always favor a conversation over reading documentation...Its out of date, subjective and conversations may uncover insights that documentation would have missed
- If you don't know who to talk to, look at the documentation to see who writes the most notes about the bit of the application you're interested in
- Use a slick editor and hide all the code. Simply read the comments left by previous developers. If you are wondering why some function doesn't work and you run across the infamous TODO comment then things become clearer
Have you heard of McGovern's law of documentation which states: The likelihood of keeping all or part of a software artifact consistent with any corresponding text that describes it, is inversely proportional to the square of the cognitive distance between them. For those who like things more simple, this translates into out of sight, out of mind....
