Documentation, where art thou?
I was in a Software Requirements Spec review meeting earlier today. The latest draft of the document was mailed to attendees about 15 minutes prior to the meeting. That peeved some people [me!]. Rightly so. And then there was the content of the document itself. I have heard just about every excuse there is to justify bad documentation or even the complete lack of documentation. Oh believe me, I have!
And then there are those in the eXtreme Programming crowd that claim that the "code is the design". Oh, is it? When one of you guys comes to work on my project, I'll be happy to give you machine code. Try and figure the system out then! The reasoning given to us is that while the code always depicts the current design, design documents always have to play catch-up and often fail. But that just imposes a flawed premise: that a design document has to rationalize every line of code and every shred of logic used. It does not! Some of us have indeed perfected the art of concise documentation. It is meant to be on-point and to demonstrate to readers accurate and adequate information. Nowhere do I make a claim of complete information.
I feel most developers shy away from writing documentation because they do not have the requisite communication skills. As Mr Ed puts it: "Documentation requires expression in natural language, and a disturbing number of developers have approximately the same facility with the written word as a high school junior". He is being kind. Most developers cannot communicate their way out of a wet brown paper bag. [I know I heard or read that one somewhere. Just can't remember where. An attribution is due]
And then there are those in the eXtreme Programming crowd that claim that the "code is the design". Oh, is it? When one of you guys comes to work on my project, I'll be happy to give you machine code. Try and figure the system out then! The reasoning given to us is that while the code always depicts the current design, design documents always have to play catch-up and often fail. But that just imposes a flawed premise: that a design document has to rationalize every line of code and every shred of logic used. It does not! Some of us have indeed perfected the art of concise documentation. It is meant to be on-point and to demonstrate to readers accurate and adequate information. Nowhere do I make a claim of complete information.
I feel most developers shy away from writing documentation because they do not have the requisite communication skills. As Mr Ed puts it: "Documentation requires expression in natural language, and a disturbing number of developers have approximately the same facility with the written word as a high school junior". He is being kind. Most developers cannot communicate their way out of a wet brown paper bag. [I know I heard or read that one somewhere. Just can't remember where. An attribution is due]
0 Comments:
Post a Comment | Home | Inference: my personal blog