Several weeks ago, Tom Johnson said on Twitter that he had decided to document software with bugs and all—essentially giving the facts—and then he would update the documentation as the bugs are fixed. A number of people replied, some of them in agreement. Tom also posted the other day on writing “fictional documentation,” admitting that he will still document how it’s supposed to work without the bugs if he’s distributing in a format that’s difficult to update or distribute.

After Tom’s tweet, I had to think about where I stand on this issue. My conclusion is that I tend to disagree with Tom’s philosophy here. I don’t think the long-term documentation should address the bugs. I hope my documentation won’t change much (a dream in an Agile environment, I know), so I document things the way they’re supposed to work.

One answer to this problem is release notes. I have been putting release notes out for a particular project that we release every couple of months, and the response has been positive. Users are calling support or sending emails to report bugs and make enhancement requests, and it’s nice to keep them informed about fixes or other progress on those items.

I don’t know how many people actually read release notes. I think when I applied the patches to RoboHelp 7, I read the notes to see what bugs had been fixed. I expect users are more likely to be interested in them if they have reported or at least encountered bugs and realize that the release notes give them an update. We include a section listing known issues and workarounds.

Really, I think documenting the software the way it works with bugs is making more work for myself, so that’s probably the main reason I avoid it. I’ve got enough to do without changing the doucmentation whenever a bug is fixed. Release notes are easier—a much smaller deliverable whose focus is what’s changed and what’s still not quite right.

I don’t think users in general expect official documentation to reveal the product’s defects. (That’s for bloggers and columnists.) The release notes help feed the conversation with the users, saying in effect that “We heard what you said about the product, and this is what we’re doing about it. We’re improving the product because of your feedback.”

Related entries (auto-generated):

Elements in Today’s Release Notes

A Process for Developing Regular Release Notes

Release Scrums: An Important Resource for the Agile Technical Writer

Consider Users’ Environment as Part of User Experience

Quick-Start Guides Require a Minimalist Mindset