Monday, November 15, 2010
Documentation cannot compile, run or do useful work...
There are documents that aid developers in understanding the problem domain that are created by architects and business analysts and then there is documentation that developers create that are mandated by the lifecycle. Care to guess which one is backtested as having the most value...
Imagine firing up Notepad and writing a few hundred thousand lines of code in it so that managers can argue over your punctuation style and practice the fine art of word tweaking, only to months or years later try to compile and run it. What do you think the outcome will be?
Documentation is a sort of error-ridden prototype whose errors and glories are equally mysterious. Have you ever asked one of those PMP-certified Project Managers why they are passionate about documentation yet when forced to tell the truth would acknowledge that documentation is largely an unscoped effort? There is no clear indication of "done-ness." The result is the effort is largely driven by an end date and the number of bodies thrown at it.
Many people complain about the lack of documentation but never acknowledge that even if documentation existed, it would more than likely not be useful. Can we agree that good documentation requires thinking about people rather than computers, something anathema to most IT developers and architects. The vast majority of developers or IT employees at large are introverts by nature, so what do you think is the outcome of having them write documentation for others to consume?
Sometimes, the process weenies periodically move away from traditional waterfall thinking and embrace being Agile and iterative, but constrain the possibilities to documentation alone. Let's agree that if you make documentation a team sport and you do so upfront, that the majority of the team at design time doesn't understand the problem space well enough to communicate anything, as you are (by definition) still exploring it.
Consider the below scenarios and ask yourself which one would you prefer:
I am of the belief that documentation should explain decisions taken and not taken, Why an approach, architecture or algorithm was selected and what else was considered and rejected. Bet the developer in most shops wouldn't have documented this since he/she may not even have visibility into the choices made along the way. So, when you are asking for documentation, what are you really asking for...
| | View blog reactionsImagine firing up Notepad and writing a few hundred thousand lines of code in it so that managers can argue over your punctuation style and practice the fine art of word tweaking, only to months or years later try to compile and run it. What do you think the outcome will be?
Documentation is a sort of error-ridden prototype whose errors and glories are equally mysterious. Have you ever asked one of those PMP-certified Project Managers why they are passionate about documentation yet when forced to tell the truth would acknowledge that documentation is largely an unscoped effort? There is no clear indication of "done-ness." The result is the effort is largely driven by an end date and the number of bodies thrown at it.
Many people complain about the lack of documentation but never acknowledge that even if documentation existed, it would more than likely not be useful. Can we agree that good documentation requires thinking about people rather than computers, something anathema to most IT developers and architects. The vast majority of developers or IT employees at large are introverts by nature, so what do you think is the outcome of having them write documentation for others to consume?
Sometimes, the process weenies periodically move away from traditional waterfall thinking and embrace being Agile and iterative, but constrain the possibilities to documentation alone. Let's agree that if you make documentation a team sport and you do so upfront, that the majority of the team at design time doesn't understand the problem space well enough to communicate anything, as you are (by definition) still exploring it.
Consider the below scenarios and ask yourself which one would you prefer:
- A developer writes a great program. He finishes it completely and eliminates all known defects. However, he does not write any user documentation or documentation for other developers that follow him. He did however write self-documenting code.
- A developer writes a horrific application. She does not finish it and it barely works. She however thoroughly documents her approach, her assumptions and the code she already has, dead-ends and rat holes she's run into and the user requirements as to how they related to the chosen design
I am of the belief that documentation should explain decisions taken and not taken, Why an approach, architecture or algorithm was selected and what else was considered and rejected. Bet the developer in most shops wouldn't have documented this since he/she may not even have visibility into the choices made along the way. So, when you are asking for documentation, what are you really asking for...
