process bits (was Re: [Doctable] Documentation Writing Process)

[John Fleck <jfleck inkstain net>]

Folks - Part two of the response to Dan's SuperMissive:

On Sun, Jan 21, 2001 at 03:01:48PM -0800, Dan Mueth wrote:
> 
> NEW PROCESS
> 
> * Add a content editor role.  The content editor goes through several
> revisions with the author, starting at outline stage and moving toward
> final product, to help the writer create documents which are structured
> and written well.
> * Add a copy editor role.  The copy editor views the document when it is
> deemed finished by the writer.  Using the GNOME Style Guide, GNOME Word
> List, a dictionary, and a good understanding of the english language, the
> copy editor fixes any mistakes in grammer, spelling, inconsistant word
> use, etc.  In most cases this is just a long list of very minor changes
> which may not require discussion with the author.  In some cases,
> the changes are less trivial and require discussion with the author.

In brief, my argument for why having these two separate editor roles
is a good idea: the involvement of a more hands-on editor during the
writing process improves writing, providing insight and feedback as
the document is being developed. The copy editing process then
benefits by having someone different do it - a different set of eyes.

> 
> - An "integrator" should assign himself/herself to the document in the
> DocTable.
> 
[snip]
> 
> Milestone 9: "Document Assigned to QA"
> (...)
> 
> - QA means making sure the package builds and installs fine, all the help
> buttons and menu items pull up the document using the correct browser, all
> screenshots are installed and displayed properly, the document is rendered
> properly by the browser, etc.
> 

Integration and QA are valuable additions as formal roles. This was
all far too vague for my liking in the 1.2 release, with a number of
people pitching in to work on this stuff but no clear idea of who was
doing what. The result was that problems fell through the cracks and
we ended up shipping some buggy documentation.

These two roles would also allow tighter coordination with the
developers, a Good Thing.

Cheers,
-- 
John Fleck
jfleck inkstain net (h)
jfleck abqjournal com (w)
http://www.inkstain.net/fleck/
http://www.abqjournal.com/scitech/