[TriLUG] Self-assessment for software documentation

[Peter Neilson]

I'm trying to put together a self-assessment questionnaire for software 
folks. There must be loads of broken or missing documentation out there, 
a lot of it masquerading as proper and complete. The idea is to have a 
short checklist for managers or others who wonder what's hiding in the 
woodwork, waiting to bite them. Here's my first-draft for a prototype. 
Suggestions appreciated.

Think of every item as having an "other" entry, even though only one or 
two show here, but let me know your fave candidates for other.

1. What documentation does your project have?
    / / User docs
    / / Requirements specs
    / / Design specs
    / / Implementation docs
    / / Documentation plans
    / / Comments in the code
    / / White papers
    / / Sales brochures
    / / "Help" commands or self-explanatory software.
    / / Other ___________________________.

2. How is the documentation used?
    / / It's part of the design and release cycle, and it up to date.
    / / We try to keep it within a month behind dev.
    / / Users send us note praising it.
    / / It's part of the product.
    / / It sits of the shelf.

2. Where is your documentation? (Iterate for each kind of document.)
    / / Printed on paper, on the shelf. I can see it.
    / / In a PDF that I can access any time I want.
    / / In a MS-Wrod file somewhere.
    / / Somewhere in a drawer or some PDF somewhere.
    / / Perl POD or Javadoc. It's *in* the code.
    / / They guy who knew where it was left last year.
    / / The contracting company has it.
    / / Other (expandify as needed) ___________________________.

3. How do you test the documentation?
    / / Users tell us when it's bad.
    / / QA & dev teams test the documentation; it goes into bugzilla.
    / / We ran spell-check on it.
    / / No one has ever complained.

4. How do you update documentation?
    / / Up-to-date dev docs and comments are part of team code review.
    / / A sharp tech writer works alongside dev.
    / / We can't find a tech writer who can understand the project.
    / / A contract tech writer comes in after the project is complete.
    / / Dev writes all the docs.
    / / Dev is not allowed to touch the docs.
    / / Dev is excluded from doc review.
    / / We hunt for the MS-Wrod source files for the PDFs.
    / / But we cannot find them.
    / / We try to find someone who knows Framemaker.
    / / The contractor has a Framemaker license but we don't.

5. How much do you worry about documentation problems?
    / / We sleep without worrying. It's all perfect.
    / / We sleep without worrying, except at 3:00 AM.
    / / We know there are problems, but the effort's on next release.
    / / Someone overseas is working on it for us at 3:00 AM.
    / / We worry constantly about (fill in:) ______________________.

6. How would you change your documentation process?