Manuals - How Up To Date?

Question

If you have a product that has been in the market for a long time, but it is still in active development daily - how often should the manuals be updated? If your users are constantly updated to the bleeding edge version due to the fact that your organization sees fit that the latest bug fixes are always in the shipped version. Meaning, you could fix a bug one day and next day it is hitting production.

Answer 1

I would update the manual:

1. For each major release, and
2. When important new features become stable and mature enough that you know they're not going to change every five minutes.

Answer 2

update the (PDF) manual any time that a code change would alter the instructions in the manual - just make updating the manual part of the release process

if the users rely on the manual to tell them how to use the product, and the product changes, then it's only common sense that the relevant section(s) of the manual should also change

Answer 3

In 2010 are we still referring to printed documentation? Why? ;)

In all seriousness, documentation (either "F1" application help, PDF, or online documentation) should be part of every single release. Zero excuses. It's that simple to "publish." As a matter of fact, IMO, there is no excuse for not updating the documentation on a regular basis (online and PDF), even in between releases, as soon as issues are known and corrected. It doesn't need the same level of QA -- not even close.

Answer 4

I assume you are talking about end user documentation. Writing documentation is a pain in the @$$ and while I've developed some technique to convince me the inverse, I still have problems with that. This is how I try to manage it:

Integrate the update of the documentation in your DoD (Definition of done)

This will ensure that your documentation will be up to date at the end of each user story completion.

Here is the definition of done we wrote. I tried to keep the original formattings, so you get the idea. It's an A4 page put on the whiteboard.

---------- 8< ------------ Cut Here ------------ 8< ----------

The not negotiable

Definition of “Done”

• Code with 80% unit test coverage, committed in repository

• Screenshots if applicable (1024x728, 395x281, 170x121 & 729x329)

• Feature descriptions if applicable (50 chars, 100 chars)

• Full end user documentation

• What's new file properly updated

---------- 8< ------------ Cut Here ------------ 8< ----------

Of course you can add a review process in the documentation. We have that since none of us are native English speakers.

One of the advantage of the Definition of Done like this is that your product is potentially shippable at the end of each user story completion.

Use this technique in combination with this one.

Answer 5

In my organization, we typically have 3 kinds of releases:

1. Engineering Release -- basically hot fix for some specific customer or some feature only a particular customer has requested on an immediate basis.
2. Minor Release -- bug fixes, incremental support
3. Major Release -- new feature support etc.

By definition, Major Release must have the relevant documentation in place both online and offline. Our tracking system ensures that documentation is very much a part of the checklist.

Minor releases need documentation only on anything new that has been added at the user perception level. So if you've included yet another heuristic that might reduce time complexity in some specific scenarios it may or may not be a significant call to put it in the pdf.

Engineering releases could do without documentation. Some informal use notes should be good enough to get started.

Answer 6

The documentation should by in sync with whatever software you are shipping to a customer. Any other mis-match is going to give you problems. And if you don't have a writer on staff, try contractors. Once you find one you like, keep him on retainer.