[TriLUG] Self-assessment for software documentation

[Warren Myers]

there's been some good discussion/q&a on this at stackoverflow.com, too:
http://stackoverflow.com/questions/304849/how-do-you-your-company-create-project-documentation
<http://stackoverflow.com/questions/304849/how-do-you-your-company-create-project-documentation>
http://stackoverflow.com/questions/241422/tips-to-create-a-useful-user-manual
<http://stackoverflow.com/questions/241422/tips-to-create-a-useful-user-manual>
http://stackoverflow.com/questions/205374/what-are-the-core-elements-to-include-in-support-documentation

<http://stackoverflow.com/questions/205374/what-are-the-core-elements-to-include-in-support-documentation>
WMM

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
> 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?
> --
> TriLUG mailing list        : http://www.trilug.org/mailman/listinfo/trilug
> TriLUG FAQ  : http://www.trilug.org/wiki/Frequently_Asked_Questions
>



-- 
Warren Myers
http://warrenmyers.com
http://www.linkedin.com/in/warrenmyers