Friday, June 26, 2009
No Documentation before its Time
Over the years management’s attempt to impose control over and visibility into the sometimes foggy and usually opaque world of software development has resulted in a mass of documentation and artifacts punctuating the process. In turn this has resulted in a revolution in the ranks of software developers who point out that they are spending more time documenting their work than in actually working. Similar protests may be heard from the ranks of business analysts who sometimes claim they are nothing more than documenters.
The issue is not really that there is too much documentation, or not enough, or perhaps more appropriately, not the right documentation for the effort being documented. The issue is what the documentation means to the people preparing the documentation.
Documentation is not a substitution for communication.
Too many business analysts become subject to the requirements document delivery syndrome. Their goal is the delivery of the Business Requirements Document or the Functional Requirements Specification rather than the definition of a solution to the business problem. Information gathering session become a means to fill in missing information in the document rather than to collaborate with the business community to define the current business processes and determine the best solution to the problem. Discussions with the solution team and other technical resources become a back-and-forth debate about what is included in the document and whether it is correct rather than a conversation about what information is necessary to understand the problem and create a solution. The business analysts focus their attention on creating the document rather than keeping the lines of communication open among all parties.
The document created as part of the information gathering or analysis process should be the distillation of the communication that has gone on before. Agreements are recorded, completed activities logged, conclusions posted for posterity, results reported. In all cases the document only provides evidence that the communication has been successful. A document created before communication is complete and final only serves to confuse communications rather than clarify. Once a document has been created, the focus is no longer on the communication, but on the document.
The issue is not really that there is too much documentation, or not enough, or perhaps more appropriately, not the right documentation for the effort being documented. The issue is what the documentation means to the people preparing the documentation.
Documentation is not a substitution for communication.
Too many business analysts become subject to the requirements document delivery syndrome. Their goal is the delivery of the Business Requirements Document or the Functional Requirements Specification rather than the definition of a solution to the business problem. Information gathering session become a means to fill in missing information in the document rather than to collaborate with the business community to define the current business processes and determine the best solution to the problem. Discussions with the solution team and other technical resources become a back-and-forth debate about what is included in the document and whether it is correct rather than a conversation about what information is necessary to understand the problem and create a solution. The business analysts focus their attention on creating the document rather than keeping the lines of communication open among all parties.
The document created as part of the information gathering or analysis process should be the distillation of the communication that has gone on before. Agreements are recorded, completed activities logged, conclusions posted for posterity, results reported. In all cases the document only provides evidence that the communication has been successful. A document created before communication is complete and final only serves to confuse communications rather than clarify. Once a document has been created, the focus is no longer on the communication, but on the document.
Labels: communication, documentation
¶ 1:36 PM
