Adobe Experience manager

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Search results

Adobe Experience manager

Fictitious Documentation

Jun 21, 2009 • general

Fictitious documentation refers to documentation that fails a lie detector test but which passes the project manager's approval.

Here's the situation: You're writing documentation that will be printed in large quantities. At the deadline for printing, the software still has a few bugs. If you mention the bugs in your documentation, it's likely the printed documentation will still be around after the bugs are fixed, making your documentation out of date. If you don't mention the bugs, it's likely that users will be confused until the bugs are fixed.

Do you lie and pretend the bugs don't exist? Do you boldly write results statements that you know are pure fiction? Or do you describe the bugs in their nitty, gritty, ugly details?

Normally, I would press developers for a timeline as to when the bugs will be fixed, and then compare that timeline against the longevity of the documentation. But projects aren't always that neat. Answers are often vague. Release fixes are arbitrary. Is the bug truly fixable? No one really knows. Maybe. Probably. When? We're not exactly sure, but it's a high priority. It should have already been fixed. Apparently we're still working out the kinks.

I think project managers are always a bit wary of bug warnings in documentation. It's hard to describe a bug in a positive way. People don't like it when you're negative. You are, after all, the voice of the team. Laying out the truth in all its detail usually breaks the standard tone of most documentation. "The Widget tab has some quirks with it. It only displays correctly in Firefox. Also, one of the fields doesn't actually send information anywhere. It was deprecated functionality from an earlier version that we decided to leave in because it was a low priority item. Avoid clicking the buttons twice unless you want the system to crash." You can't really write that kind of stuff.

When it comes to truth, my approach is to be candid and honest in formats that live on the web, which I can update on the fly. But when I'm printing hundreds of copies of a guide, which I know will be pinned up on walls, filed in desk drawers, and laminated for long-term reference, I often lie and don't mention the bugs, hoping that developers will soon fix them and convert my fiction into truth.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.