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.

  • 1
    Are we talking printed or on-line manuals? There are at least a couple of different forms this can take.
    – JB King
    Dec 22, 2010 at 23:05
  • Online (PDF) manuals Dec 22, 2010 at 23:07

6 Answers 6


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.

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

  • 1
    so if no technical writer on staff, then update it yourself? Dec 22, 2010 at 23:48
  • @0A0D - if you don't have a writer, you don't have much choice, unless there are testing or support staff who can do it.
    – JeffO
    Dec 23, 2010 at 1:34
  • 1
    I have the document 'source files' as part of my projects. They are always updated at the same time as code. They are versioned with releases and managed using the same source managmnet tools as the rest of the project files (go Mercurial!). I have a pretty standard set of manuals to go with a project and these are all managed in the same way (user guide, config/installation guide, release notes and our own technical ref/spec documents).
    – user11465
    Dec 23, 2010 at 10:14

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.


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.


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.


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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.