RSS 
Email 
Twitter
FacebookFictitious Documentation
June 21st, 2009 | Posted in Technical Writing 12 Comments »
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.
Our policy is to document the product as it should work, provided the engineers say they’re going to fix the bugs within a year, and then document the bugs under the headings “Known Problems” and (perhaps) “Manual corrections” in the release notes.
Johan, thanks for the comment. That sounds like a good strategy.
Indeed, we document how the product is supposed to work. Because documentation is written in the development phase, bugs and missing functionality are common, it can’t be otherwise.
Normally, by the time the product ships and the documentation is finalized, bugs tend to be fixed — or, if necessary, documentation is updated to match the product.
When you say “the product ships,” do you really ship it? Most of the software I document is run from a web browser, and we can update it periodically with fixes and other enhancements without requiring the user to reinstall the application. Because of this, there’s no clear line about when a product physically ships.
Yes a document should be as it is described. It should be able to stand on its policies. If a bug is found as stated in the document, then the engineers should be there to fix it up.
Engineers can’t fix all the bugs before release in almost any software, I think. We have scores of bugs in production. But they’re so small and rare that they weren’t prioritized above the set deadline to deliver.
“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?”
Risk management would be useful here: what is the nature of the bug and what hazard does it pose to the user and their goal?
In my career, I have never found a software or piece of hardware that functions 100% accurately with the requirements.
It is a razor-blade line that I feel I have to walk when writing “What I see is what you get”, or “What is supposed to be is what you get”.
Ethically (STC ethical principles for technical communications, 2006), I am bound to notify my client which information is not accurate at the time of the writing. At final review, the client takes responsibility for making the choice of what is “Fact or Fiction.” Regardless, of whether the information is a bug, or in development, or whatever…if I am writing then my code of ethics writes the right words.
Tom, I’ve never seen you use the term “release notes” in your posts that describe how your doc team works. And I don’t understand that.
Paul
Twitter: @bkwdgreencomet
Hi Paul, thanks for the comment. I’m not sure what you’re asking, though. Release notes are a common deliverable in software documentation. They announce what’s new in the latest version of the software. Release notes may also note existing issues or bugs. Can you clarify your question for me? Thanks,
Tom
[...] Fictitious documentation refers to documentation that fails a lie detector test but which passes the project manager’s approval. (zum Artikel) [...]
Reminds me of my first documentation project ever, which was rather a prototype than a final product. Writing a novel would have been easier. The good thing was: The project manager liked it and two years later the final product did what the documentation said…