Writing The Right Things Down

I have discovered, in my travels, that companies love to write things down. The more that's written down, the better. The thing they have an issue with is the writing down of the RIGHT things to be useful.

For example: Companies love timesheets. But how many of them would prefer an honest timesheet and how many of them don't allow you to book more than 37 hours a week, no matter how long you worked. Or don't have an entry for "time spent filling in timesheets".

I'm looking at a "technical specification". I get to halfway down page 10 (of 26) before I find ANY text that isn't boiler-plate: lists of people to review this (none of whom have), sign-offs (what are they for?), detailed instructions on how to fill in those bits... ten pages of stuff that someone has written but basically wasted a lump of their life doing.

And the rest of it contains treasurable gems of prose:

"4.3Operational Support - Operational support of the solution leverages existing operational procedures, including BMC Patrol for Enterprise Management"

A 26 page document which should be 4 pages long, and yet still fails to have content. This is not at all unusual.

Why doesn't anyone write down brief concise meaningful stuff instead of vast acres of meaningless jargon? Has no-one noticed this is what they're doing? Or are they engaged in some complex DoubleThink?

-- KatieLucas

I have found that there are many forces conspiring to increase weight of documents. The timesheet issue is one of my PetPeeves? - all they want is for you to show you've worked the required hours, so they can claim they are not exploiting your exempt status, but also to ensure that you are not avoiding their mandate to be working those hours, necessary or not. I am quite annoyed by timesheet policies that actively counter any attempt to accurately depict my work time.

Among the forces involved in increasing the weight of documents:

A perceived, but incorrect, view of documentation as supremely important.
A real need for documents. Sometimes, it's more important to record a difficult and complicated business decision than to ensure that it's pretty.
Inappropriate placement of MetaData. Revision histories, signoffs, and other auditing records usually should not be placed in the document itself; they should be kept separate from but connected to the original documentation.
Simple repetition. Often, it's easier and quicker to copy and use a cruft-filled template than to invent a whole new document layout from scratch every time.
A lot of people just can't write very well. GoodDocumentation? should be well-written, but how many people really can write in a clear, concise style? When you get Frank the Unix sysadmin who spends sixteen hours a day at a BashShell? prompt to write end-user documentation, the documentation is likely to be difficult to read (it may not; I'm just pointing out that technical skill does not necessarily translate into writing skill).
The auditing or some internal control department requiring those fluff such as revision histories and signoffs.
CoverYourAssets, especially in places with lots of internal politics, documenting who has seen the document is more important than any other content of the document.

Another factor is knowing the audience for the document. My last company had strict documentation guidelines that didn't make sense to me until I figured something out. All documents were designed for the company founder, who had to approve the documentation before we started a project. We had to emphasize goals and general ideas, instead of writing a feature list and tutorial that most engineers and end-users would prefer.

When the Right Things you write down are personal and for personal use, you might considerL

CategoryDocumentation