Quote of the Day
No management system can substitute for hard work. A manager who does not work hard or devote extra effort cannot expect his people to do so. He must set the example. The manager may not be the smartest or the most knowledgeable person, but if he dedicates himself to the job and devotes the required effort, his people will follow his lead.
— Hyman Rickover
Figure 1: Many People Believe that Every
Snowflake is Unique (Source).
I had dinner the other night with a networking engineer who works as a contractor. He is known as a person who writes well, and he is finding that many of the companies that he works for are asking him to determine how their networks operate and to write down what he discovers.
He related a story from a recent assignment where he was hired by a small, high-tech firm to reconfigure the routers and switches on their network. When that task was done, they asked him to investigate other aspects of their network and to write down what he finds. He asked his manager if the company had a documentation template that they wanted him to use. The manager responded as follows:
Documentation template? You need to understand that our documents are like snowflakes – every document is unique.
I cannot imagine a manager responding like this – think of all the problems this lack of standardization creates:
- Engineers waste time on unproductive style decisions
- Every engineer now need to know how to create tables of contents, appendixes, etc.
- When the original author is not available to maintain the document, someone else now has to figure out each documents style system rather than working with one company standard.
- The documents will have a wide variation in look, feel, and completeness.
As I have stated before, I am quite emphatic on documentation standards and templates. I make sure that every engineer knows the various document standards (e.g. short form, long form, mathematics, requirements) and how to use the templates.
Unfortunately, the tools used by most organizations do not promote easy standardization. When I worked as a proposal manager for ATK, I would frequently work with partners who had different documentation tools that ATK, so I have used every documentation tool known to man short of stone tablets. I only have worked with a few that made documentation standardization easy.
Secure Computing had the best documentation system I have ever used. It was based on LaTex and enforcing standards was easy because they used a standard template file. Their requirements were stored in DOORS, and they did a very good job of linking the DOORS database to their documents.
The worst tool I have used for engineering documents is Microsoft Word. Its style system is okay if you have disciplined authors working on small, one-person documents, but it is simply too difficult to enforce standards when being used on documents with multiple authors (e.g. proposals). I cannot tell you how many hours I have spent cleaning up formatting issues in large Word documents.