The external release notes (which go to customers) document new features, major changes or enhancements, and any bug critical enough that a majority of our users suffered from it. And in that case, I spin the text to show how great we are for fixing the issue.

The idea is that we only send information to clients when it’s something that affects them. For example, they would notice an interface change or a new feature. Everything else is left in the internal notes, and it’s up to the account managers to alert their clients about the bugs that affected them specifically. Seems to work ok so far.

Yesterday I just had an issue where I documented a troubleshooting procedure. The procedure was effective, but the lead developer said it reflected poorly on the software itself. Instead of documenting a workaround, he suggested that the problem be replicated so the developers can fix it. (It’s a common strategy, it seems, for developers to say that software problems are bogus until buggy behavior can be convincingly replicated. As a result, my documentation is pulled and the team awaits more bug reports.

Instead of writing end user documentation, I find that I spend a lot of time writing bug reports. Is that better for the end user?

If my documentation even so much as acknowledge that it doesn’t work the way it’s supposed to, the documents aren’t approved. I don’t worry as much about the ethical dimensions as the possibility that pushing things under the rug will reduce the quality of software over time.

If a feature does nothing, I’ll simply state that the feature is not currently active – no explanation required.

If a feature is broken and the development team is planning a fix, I’ll ignore it – we have excellent call-in tech support, and my company prefers to handle that kind of thing there.

If a feature is broken and no fix is planned (or a fix is a long way off), I’ll explain the current function and note the problem as a limitation, then link to or explain an alternative method that avoids that limitation. No judgment necessary.

Release notes are a mixed bag. We have a general policy that if we fix a non-critical bug, it only goes in the release notes if we had a customer call about that issue. There are exceptions, but that’s the starting point for those decisions, which I make along with the programming manager and the product manager.

I feel it’s a fair trade, especially since our customers have a long habit of simply picking up the phone and calling support when they run into unexpected behavior – we tend to hear about it when they find a bug.