Re: Documentation development processes.

[Pat Costello <Patrick Costello ireland sun com>]

Hi Greg,  

Thanks for your reply to my brief summary of documentation development 
processes. And believe me, it was brief, the original document on this topic is 
a hefty tome. Notwithstanding, you posed a few points which I should answer, 
your points are in inverted commas, my responses are arrowed: 

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

>>
Well, the better developed your documentation process, the better your end 
product. You can develop your documentation with a streamlined process, but you 
must accept that you are making trade-offs. Ultimately, the dependency is the 
level of professionalism, accuracy and quality that your end-user audience 
expects. 

You are right about the manpower situation though, working with voluntary 
contributors, no matter how enthusiastic or productive, we will always be 
restricted in the number of man-hours available. 
>>

"I'm not clear on what comes out of this stage (technical development cycle).  
Is this, say, a draft version of the application manual, or is it something 
else?"

>>
It is, as you say, a draft version. 
>>

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

>>
A review issue is a formal draft issue to a reviewer or team of reviewers, 
rather than an informal what-do-you-think issue. A review issue specifically 
calls for comments by a certain date, and carries a review draft version number.
>>

"At the end of this process (information design cycle), an outline is created 
for the structure and content of the manual/document, right?" 

>>
The writer and information-design reviewer would develop an outline structure, 
yes, but at the end of this cycle the writer would also have applied the 
structure to the content. At this stage the manual should be coming close to its 
final shape.
>> 

"At this point (end of editorial review cycle) 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."

>>
Yes, that's all correct. 
>> 

"This (indexing cycle) 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."

>>
Indexing is a critical part of document navigation, and as such a major addition 
to quality. We have to do it, if we are serious about meeting end-user 
requirements. 
>>

"This (usability test cycle) 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).  :)"

>>
You are right, again resources is the critical issue. Notwithstanding, usability 
testing produces remarkable improvements in documentation quality. If you can do 
it, you should do it. As of right now, the only thing that I can say is that the 
Sun team will probably do usability testing on Gnome documentation that is going 
to be packaged with Sun systems. We will of course make public any findings so 
that other Gnome documentation can leverage from this work. 
>>

"I expect that most of our authors will have to be aware of all of these 
(quality review) 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."

>>
The authors should, of course, apply all agreed standards to the document. The 
job of the quality reviewer is to make sure that the writing is consistent with 
other parts of the documentation, that standards are being applied 
appropriately, that new developments elsewhere in the project do not affect this 
document, and so on. A "buck-stops-here" kind of a role.

The quality reviewer is a single individual with product knowledge, and 
preferably overview knowledge of the project. The quality reviewer should be 
intimate with all of the standards and requirements and should be a master of 
English usage. 
>>

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

>>
By requiring formal approval for documentation before release, you create an 
acceptance process. Providing the approval reviewers take their role seriously, 
you establish a level of quality standard for all released documentation. 
>>

I think that covers all your points...

Pat