Poe's Prose: Be afraid, be very afraid!

A Documentation Horror Story

By Kathryn Poe

Okay, I will admit it right here and now: I love Halloween! You get to wear strange costumes and get free candy. What is better than that? I also like a good haunted house where I can get a good scare and live to tell about it. There is just something liberating about screaming your head off in public. In my 10-odd years of technical communication I have occasionally felt the need to scream in the workplace as well. Sadly, we don't usually have that option.

In our professional life as technical communicators you will be scared by many things: documents with 14 different fonts on one page, hard-coded TOCs, and 23^rd-generation copies of documents that resemble gray cave paintings more than technical information. I suspect every writer has their horror stories about bad things that happen to good documents. I thought this was the perfect month to share my favorite with you, so go put on your spooky music.

Frankendoc – A true story

I thought that working with award-winning scientists would be a challenge for me. I was right. It was, but not in the way I had expected. I was sent a "little paper" to clean up and put out in the Knowledge Management repository as a reference. After I explained that a soft copy was necessary for this purpose, their little missive appeared in my inbox. It was a healthy Word doc of 61K, so I popped it up figuring on some minimal punctuation or grammar fixes. I was mistaken.

Here's a little document status laundry list of what I found:

The first page was labeled "Table of Condense" and consisted of a list of terms and on what page you would find them.
The TOC was completely hard-coded so it had been updated by hand. I also think they broke the record for most tabs on a single page.
There was no index in the back of the book although I found a blank page with the word Index at the top. This index was not included in the TOC.
Since there seemed to be a great deal of white space, I checked the margins and found them each at two inches. Perhaps they planned to bind the document on a different edge for each occasion?
Within the text they had used styles. I found five Normal tags defined, including NormalBob. Apparently Bob required his own brand of normal, though all the body text looked the same.
They used the word which throughout, even in places where that would have been more appropriate. When I asked about this I was told which was more formal and thus always used in scientific writing.
On a few select pages were really odd-looking tables. Selecting one, I found they didn't act like normal tables. They turned out to be a series of text boxes abutting each other to appear "tablelike." (It could have been worse. I once had a client who tried for hours to construct a table by drawing boxes with the Word Drawing tool and typing in them. I am not kidding!)
Word told me this document was 314 pages, but there were no page numbers to be found. I wondered what happened if they printed and dropped this puppy. Perhaps they were brilliant enough to reassemble it without the need for job aids like page numbers.

And my favorite feature: I reached a page that resembled nothing so much as Klingon. With brief investigation, I found that the footnotes were mapped to webdings instead of a real font. This made them quite long, pages in fact, and very tricky to read as they consisted only of symbols.

These were very bright folks who had worked long and hard on their document.
They were proud.
They were technical.
They were clueless about documents, format, and their chosen tool. I offered to go up and teach a basic Word class for them. I was informed that they did not require any training as they used the tool successfully every day. It was all I could do not to ask, "For what?"

It turned out well in the end. I billed many hours reworking Frankendoc and we all lived happily ever after.