Re: Documentation development processes.

["Dan Mueth" <dan eazel com>]

On 22 Jan 2001, Gregory Leblanc wrote:

[SNIP]

> > Usability Test Cycle
> > 
> > Once the index is complete, a good exercise is to do a usability test on the 
> > documentation, for example how quickly can users find a given piece of 
> > information, or how easily do they perform tasks detailed in the manual. If 
> > major changes result from the usability test cycle then the copy-editor should 
> > look again at the parts that have changed substantially. 
> 
> This sounds awesome, but somehow I don't see the GDP having the kind of
> resouces necessary to be able to do this, although we certainly won't
> stop somebody like Sun's GNOME useablity labs (or whatever they're
> called) from doing this (hint, hint).  :)
> 
> > Quality Review Cycle
> > 
> > In ideal circumstances, someone who knows the product, the style
> > requirements and special requirements such as translation, should do
> > a final quality review.  There should be only one quality review.
> > You can review the index at this stage.
> 
> I expect that most of our authors will have to be aware of all of these
> issues, so that they can take them into account while writing their own
> docs.  Is this normally done by a special team, or just by other authors
> who have enough free time to take a look at another product?  For LARGE
> documents, I suspect that this could be done by someone who is writing
> another section of the document, as they'll be in a position to have a
> great deal of knowledge about the product in general, plus the knowledge
> that authors will have.
> 
> > Approval Review Cycle
> > 
> > All of the lead reviewers from the previous cycles should look through the 
> > documentation one more time and approve the manual for release. There should be 
> > only one approval review. 
> 
> Assuming that no mistakes are found.  I think we could probably manage
> this one in the GDP.  Dan, what say you?  Is this doable, and worth
> doing?

I'm not sure I understand the difference between the Quality Review and
Approval Review.  I thought I was being somewhat bold in adding the
different editorial roles, indexing role, and QA role.  I certainly would
not be against a quality/approval review if I thought we could pull it
off.  As Pat stated, it really comes down to resources.

So, if we have the resources to do this, it would be great.  However, we
may want to ease into this.  I would suggest we *not* add this step to the
process until we have people filling the other editorial roles.  If we
find editors very easily, or somebody is really dying to do this review,
then we can surely add this step.

The other concern is turn-around time.  Each step we take draws out the
time between when the application freezes and when the application
ships.  We have to be sure that we can get through the whole process in a
reasonable time frame so the application doesn't sit mothballed for 6
months between being developed and finally being released.  In order to
get fast turnaround times, we need to have a lot of people working in
parallel.  This may be possible, but we will need to ramp up to this
slowly as we accumulate more contributors and refine our process.

Dan