Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
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 '10 at 23:05
    
Online (PDF) manuals –  staticx Dec 22 '10 at 23:07

6 Answers 6

up vote 4 down vote accepted

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.
share|improve this answer

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

share|improve this answer
1  
so if no technical writer on staff, then update it yourself? –  staticx Dec 22 '10 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 '10 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 '10 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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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