re: [Doctable] Documentation Writing Process

[Gregory Leblanc <gleblanc cu-portland edu>]

ok, I'm throwing this at the gnome-doc-list, since there's plenty of
interest from people (Dave is even in #doctable as we speak), and since
the gdp list is pretty low traffic.  I've left David, Ricardo, John
Sheehan, and Pat Costello on the CC list since I'm not sure of their
subscription status to the GDP mailing list.  Many of the discussion
points arising out of the doctable are actually general GDP issues, so a
Doctable mailing list isn't what we need, for the time being.  If you
can stick/leave [Doctable] in the subject, that should help people who
don't care to filter out these discussions.

On 21 Jan 2001 09:29:49 -0700, John Fleck wrote:
[snip]
> I don't think these are mutually contradictory. In the professional
> environment in which I work (a newspaper - quite different than doc
> writing but facing many similar issues) there are two separate types
> of editing - one during and at the end of the writing, of the type
> Gregory suggested in which an editor is involved in the development of
> the document (I'll call this "content editing"), and a second, more
> detailed and formal copy editing process that looks at style,
> spelling, grammar.
> 
> Using the DocTable steps mentioned by Dan above, this could be
> incorporated as:
> 
> > 1) Assigned to writer/"content editor"
> 
> where the editor here is playing the role Gregory described helping
> structure and organize the document's content, separate
> from the later "copy editor" role.

I like formalizing this role, as I think it will make for better docs,
and an easier time writing those docs, since you'll have somebody who
has said that they'll take out enough time to read over drafts a couple
of times.  The burden is still mostly on the writer, but when they get
stuck on something, they have someone who they can turn to, rather than
just tossing it out to the docs list, which isn't always that
responsive.


> The copy editor function should be defined as explicitly
> different than the "content editor's" role, and done by someone
> other than the "content editor". This is important, as a new critical
> eye needs to be applied to the doc at the copy editing state.
> 
> I think Dan's discussion of this falls short of the formality I'd like
> to see:
> 
> > 1) Writing (This includes one or more writers working on a document,
> > hopefully getting feedback from gnome-doc-list, editors, other writers,
> > application developers, their dog, etc.)  Note that the editors play a key
> > role here, but I am still calling this the "writing" stage in that the
> > ball is in the writers court to do most of the work and drive the process
> > along.
> 
> This seems more like the way we do this now, with a sort of informal
> "could you give this doc a look?" process. Sometimes this works and
> sometimes it doesn't. How many times have you posted a note to the
> list asking for feedback on a draft doc and gotten zero feedback? How
> many times have you done the same with a developer and gotten zero
> or perfunctory feedback? I think the process would be improved with
> the formal addition of a "content editor" with explicit responsibility
> here.
> 
> Formalizing our processes in this way would improve the quality of our
> docs - no doubt. But we're really here talking about a change in the
> GDP processes, with the DocTable only a tool for managing those
> processes. We need to evaluate whether we have the time and human
> resources to accomplish this. (I believe we do and should, but we need
> to be explicit.)
> 
> I'd be very interested in hearing from the folks at Sun about how they
> manage this process.
> 
> Other notes:
> 
> On the translation steps, aren't there going to be many branches at
> this point on the trunk of our little tree, lots of 7)'s and
> 8)'s for lots of different languages? Assume this has been discussed
> and will be handled appropriately.

Well, it's not been discussed just yet, but I do have some idea how I'm
going to handle it.  I want to get the GDP sections of this finished
before I start working on the GTP stuff, just to keep the workload
manageable.

> Dan wrote:
> > (We may even put a final step 9 in there for QA to make sure it integrates
> > with the software and help system properly and gets installed correctly.)
> 
> This is *way* important. My experience suggests the responsibility for
> this step needs to be explicitly given to someone - (they can either
> do it themselves or work with the developer to make sure it gets
> done). There was way too much vagueness about this step with Gnome
> 1.2, and I'm worred about 1.4 in this area.

Yeah, I agree.  I think John is proposing the following roles, for each
application manual.
Author
Content Editor
Copy Editing
Indexer
QA person

This looks like a lot more work, but I don't think that it is, as we're
really just better defining the process by which docs get written.  I
think we've got the personell available to be able to do this, and it
should drasticly improve on the quality of our documentation.  I'm sure
there are more ideas to be hashed out.  I'll post the earlier
discussions on the doctable to the website where I'm doing most of the
work on the new design, and eventually the new implementation.
http://leblanc.dhs.org/new_doctable/
Later,

    Greg