The Wary Engineer’s Notebook – Part 4

This is fourth and final (for now) part of “The Wary Engineer’s Notebook”. In this installment we’ll take a quick but jaundiced look at documentation.

Just remember that this is all intended to be humorous in a satirical, tongue-in-cheek way, so please don’t get spun up thinking I’m trying to insult you or your dress code. I wouldn’t dream of it. Honest.

If you’re not sure what this is all about then please go back and read Part 1 first.


Let’s face it, most engineers and managers are selectively illiterate. Sales types are usually technically illiterate, so don’t ever expect them to read and understand the technical data they should know in order to market the product effectively. They will almost always screw it up and sell something that either doesn’t yet exist or can’t be built with current technology.

In the case of engineers and project managers their selective illiteracy is obvious from the simple observation that no matter how often they are presented with essential documentation and asked to read it they will still ask stupid questions during reviews, do stupid things that the documentation clearly defines as a stupid thing to do, and make stupid and incorrect assertions to other engineers or to management that reflect badly on you. The usual excuse is “I’m overworked and I didn’t get a chance to read it”, which is rather odd, since they often have time to play a video game, read the latest technical journal or issue of Discover magazine, or even go have a few beers after work. They just don’t have time for you.

Another bit of evidence for illiteracy is that most engineers either can’t or won’t write anything down. Or, if they do, it’s terse to the point of bordering on a Zen Koan, and therefore utterly useless to anyone other than themselves (assuming they can even remember why they wrote it down in the first place).

Operations Manual

Generally speaking, no one reads the operations manual, also known as a user’s manual or user’s guide. It is usually created because it’s a contractual requirement. This is compounded by the aforementioned fact that most engineers can’t or won’t write. Sometimes an outside contractor is brought in to write the required document, only to be promptly discarded like used toilet paper as soon as the final draft is accepted and approved.

Design Description

Obstensibly the design description is supposed to describe, in some detail, how the software, hardware or whatever will actually be implemented and how all the various bits and pieces will work with each other. It is also supposed to happen more-or-less in sync with the development of the low-level implementation requirements, but seldom does. In reality the design description is typically written after-the-fact as an “as-built” document. That is assuming, of course, that anyone can be coerced into even writing it. Sometimes the same hapless technical writer who was conscripted to write the operations manual will also write the design description.


0 Responses to “The Wary Engineer’s Notebook – Part 4”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Follow Crankycode on

Little Buddy

An awesome little friend

Jordi the Sheltie passed away in 2008 at the ripe old age of 14. He was the most awesome dog I've ever known.


%d bloggers like this: