[TriLUG] Self-assessment for software documentation
volcimaster at gmail.com
Mon Jul 6 19:33:27 EDT 2009
there's been some good discussion/q&a on this at stackoverflow.com, too:
On Mon, Jul 6, 2009 at 2:18 PM, Peter Neilson <neilson at windstream.net>wrote:
> 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
> 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?
> TriLUG mailing list : http://www.trilug.org/mailman/listinfo/trilug
> TriLUG FAQ : http://www.trilug.org/wiki/Frequently_Asked_Questions
More information about the TriLUG