Comments on: Fictitious Documentation

By: Marc Achtelig

Marc Achtelig — Wed, 23 Dec 2009 16:06:04 +0000

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…

By: Wie wahr - fiktionale Doku - Doku-Hotline - Birgit Grossmann über Texte, Technik und technische Dokumentation

Wed, 15 Jul 2009 22:12:00 +0000

[...] Fictitious documentation refers to documentation that fails a lie detector test but which passes the project manager’s approval. (zum Artikel) [...]

By: Tom

Tom — Fri, 10 Jul 2009 14:12:00 +0000

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

By: Paul K. Sholar

Paul K. Sholar — Fri, 10 Jul 2009 06:13:35 +0000

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

By: Tom

Tom — Tue, 23 Jun 2009 04:20:47 +0000

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.

By: Tom

Tom — Tue, 23 Jun 2009 04:17:38 +0000

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.

By: Tom

Tom — Tue, 23 Jun 2009 04:15:56 +0000

Johan, thanks for the comment. That sounds like a good strategy.

By: Kendall-Johns

Kendall-Johns — Mon, 22 Jun 2009 19:59:43 +0000

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.

By: Milan Davidovic

Milan Davidovic — Mon, 22 Jun 2009 12:53:20 +0000

“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?

By: Tim Morrow

Tim Morrow — Mon, 22 Jun 2009 11:32:41 +0000

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.