Re: Documentation development processes.

[John Fleck <jfleck inkstain net>]

Pat - Thanks for this very helpful guideline. I think the GDP's
resource limitations preclude us from doing something this rigorous,
but that shouldn't stop us from aspiring to taking some steps along
these lines, as Dan has suggested, to tighten up our processes and
therefore improve our quality.

Below:
> = Gregory Leblanc
> > = Pat Costello

> 
> > Technical Development Cycle
> > 
> > During this stage the writer works with the main technical information resource 
> > to gather accurate information and present the information accurately in a 
> > document. Usually, there are two review issues in this cycle. You can regard 
> > this cycle as a technical content edit.
> 
> I'm not clear on what comes out of this stage.  Is this, say, a draft
> version of the application manual, or is it something else?
> 

I'm unclear who the "technical information resource" is. Would this be
a developer? 

> > Information Design Cycle
> > 
> > During this stage the writer works with an experienced peer reviewer. In Sun 
> > this would be the documentation project leader. The peer reviewer helps the 
> > writer to structure the information in the most effective way, and ensures that 
> > the writer is applying agreed style guidelines. Typically, there are two review 
> > issues in this cycle although the document could pass back-and-forth informally 
> 
> What is a "review issue" as you refer to it here?  I imagine that you
> used this term because it's something that you're familiar with, but
> I've not seen it used.  
> 
> > between the peer reviewer and the writer. You can regard this cycle as an 
> > information-presentation and structure edit. I hesitate to call this cycle a 
> > content edit, because the interaction between the writer and the reviewer is 
> > more of a joint-venture than an editorial activity. 
> 
> At the end of this process, an outline is created for the structure and
> content of the manual/document, right?
> 

This seems very close to the "content editor"/writer process discussed in
Dan's missive.

> > Editorial Review Cycle
> > 
[snip Pat's description of copy editing process]
> 
> > Indexing Cycle
> >  
> > When the writer has incorporated all of the comments from the copy-edit, then 
> > indexing can be completed. The writer may well have started indexing stable 
> > areas of the document earlier, but it should be finished now. The editor may 
> > want to see the index, but it doesn't need to be formally edited.
> 
> This is something that we've done none of, or almost none of, in the
> past, but something that I think will be a major part of the next few
> releases of GNOME.  The result of this process is pretty clear, I think.
> 
> > 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).  :)

Greg's quip nothwithstanding, this would be a very good thing to
incorporate into our process. How might we do this?

Pat, why is this done at this late stage in the process? What happens
if this causes changes?

> 
> > 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?
> 
> > Localization Cycle
> > 
> > The most ideal way for translators to work is if the material is 100% stable. 
> > This is not always possible, nevertheless, the bulk of localization work should 
> > take place after approval of the documentation.
> 
> Sticky issue here, as I don't really know what it would take to
> translate a document.  Does anybody have some written guidelines for
> authors that will help to make their documents more easily translatable?
>

FYI: The Gnome Style Guide will have a chapter on this.
 
> > Submission and Release Cycle
> > 
> > At this stage someone, usually a release engineer, would test the integration of 
> > the documentation with the rest of the product. 
>
> 
> > The core point that I'm trying to make is that copy-editing is only one aspect 
> > of the review process that is required to create good documentation. I 
> > realize that the above process is very formal and demanding on resources, but it 
> > does produce excellent results. A lot really depends on the resources available. 
> 
> I'd certainly like to see a more formal process for GNOME than what we
> have now, and frankly I think it will be demanded in order to produce
> the quality of documentation that we need.  I'm sure I wanted to put
> some summary things here, but I can't remember what they were, it's been
> a couple of hours since I started on this mail.  :)  (BTW, are you folks
> from Sun on the GDP mailing list, or shall we keep you on the explicit
> CC list?).  Later,
> 
>     Greg


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