RE: Benchmarking Technical Documentation

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

I must be extraordinarily lucky, or completely out of the ballpark.
(Katherine, I'm not picking on you, yours just happened to be the last post
I received!) In this discussion, nobody has yet to mention using and testing
the product as part of the process. I can't possibly be the only lone writer
out there serving triple duty in design recommendations and QA!  In eight
years. I've yet to document a piece of software that I didn't use and test
thoroughly BEFORE I let anyone review documentation. Most of the time I help
design it, and I've yet to meet a professional development and QA team who
didn't welcome the additional expertise.  By the time it's working in a test
environment, I already know exactly what it's going to do, where the current
problems are, and when they're likely to be fixed.  

Tech comm will continue to be relegated to secondary or tertiary importance
in a development environment as long as practitioners rely on all the other
SME's to dictate process and timelines.  And as long as we view
documentation as some separate function from all the development, design and
support efforts that go on.

Connie "on her SME soapbox again" Giordano





-----Original Message-----
From: Katherine Turner [mailto:katherinet -at- csl -dot- com]
Sent: Tuesday, July 24, 2001 11:46 AM
To: TECHWR-L
Subject: RE: Benchmarking Technical Documentation


I know our support team welcomes documentation as it means that the number
of support calls and emails is reduced if the documentation is good. This
means that support, to some degree, is reliant on documentation.

Some of the other issues raised to do with readability, content, format etc
are all to do with the documentation process that is in place.

This is how we create documents:

1. Outline - an outline is written which says exactly what will appear in a
document. It is either written by a member of the docs team or an SME.
2. Outline Review - the outline is reviewed by an SME
3. Write - the document is written
4. Technical Review - the document is reviewed for technical accuracy and
completeness. This is always done by an SME. This SME may or may not be the
same as the SME who did the Outline Review.
5. Revisions - revisions made based on technical review. These revisions are
made by the writer.
6. Readability Review - this is done by a member of the docs team. I believe
that this is an essential part in the clarity, readability, grammar etc of
the document. 
7. Revisions - revisions based on readability review. This revisions are
made by the writer.
8. Formatting, indexing.

Stage 8 encompasses everything that is left, basically because it's being
done by the same person.
Stage 6 onwards are "nice to have" but not essential stages. 

I do think the readability review is extremely important but it's down to
pressures and timescales as to how much gets done. If we are under pressure
we try and ensure that as much as possible of the 8 stages is done although
all revisions may be done at the same time. As all documentation created by
[SNIP]

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.