I just replied to an EETimes article that presumed to place the blame for poor documentation on the engineering staff. The title of the article was ‘Engineers on creating better technical documentation‘.

I said that poor documentation is not a problem engineers created or perpetuates. Engineers are trained to write good documentation. It was part of all of those lab experiences (aka lab notebooks) that set the precedent for an engineer way back in university for writing proper procedural documentation.

Procedural documentation as was taught at my university (Texas A&M, electrical engineering) was that if you didn’t write it down, you didn’t do it. And if you didn’t adequately explain the procedures: lab set up, test methodology, and results then it was negatively reflected in your grade.

Hence, you either learned how to properly do documentation or you switched to an avocation more suited to your sloppy habits like the business department.

So let’s place the blame for poor documentation where it really belongs:  1) non-engineers working in engineering positions or 2) the managers who didn’t adequately plan or fund for the project’s documentation effort.

Fred Brooks, in quite possibly the best ever written book on the subject of software engineering, ‘The Mythical Man-Month: Essays on Software Engineering’, said that one of the principal reasons for project failure was to underestimate the testing and documentation phases.

Advertisements