Documentation development processes.

[Pat Costello <Patrick Costello ireland sun com>]

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: 

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. 

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

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. 

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. 

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. 

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. 

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. 

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. 

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. 

Regards, 

Pat