Re: Documentation development processes.

[Gregory Leblanc <gleblanc cu-portland edu>]

On 22 Jan 2001 17:48:05 +0000, Pat Costello wrote:
> Dan and John, 
> 
> In response to the conversation that you are having about an editing process for 
> Gnome documentation, here is a brief summary of the way that a technical manual 
> is developed in a corporate environment, such as Sun: 

I love how you guys define "brief".  :-)  I'm going to stick a couple of
comments here, assuming that people have read your message.  I'm not
terribly sure that we need a process as complex as this one.  I'm also
not sure that we have the manpower to pull this off, even if we did need
such a sophisticated process.  

> 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?

> 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?

> Editorial Review Cycle
> 
> During this stage the writer works with an editor who reviews the material 
> against the agreed style guidelines. You can regard this cycle as a copy-edit. 
> There is usually only one copy edit, although the editor may ask for a review 
> check to see how comments are being used.  It is very difficult for an 
> editor to do a good copy-edit if the previous two review cycles have not been 
> rigorously carried out. Also, the material should be stable before it goes to 
> the editor. 

At this point the document is complete from both a structure/design
point of view, and from a content point of view.  The changes to the
text of the document are complete.  

> 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).  :)

> 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?

> 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. 

Does this just refer to being able to use the help key/menus to get to
the manual, or is there more to it?  If the former, I expect that this
will not be done at the end of this cycle, but rather closer to the
beginning, so that more people have it available to them for
review/testing.  This is a cultural thing, not necessarily anything
technical.

> 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