Re: Documentation development processes.

[Pat Costello <Patrick Costello ireland sun com>]

Hi John, 

Thanks to your reply to my mail about documentation development processes. You 
made some points so I should reply to them, your points are in inverted commas, 
my responses are arrowed: 


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

>>
I recognize the resource limitations implicit in a volunteer team, nevertheless 
we should try to implement defined stages with specific goals, and try to fit 
our manpower around the goals. There is nothing to prevent some contributors 
taking dual roles, for example information-design peer reviewer could be the 
same person as the quality reviewer. 
>>
 
"I'm unclear who the "technical information resource" is. Would this be
a developer?"

>>
You are right, the technical information resource is usually the product 
developer, but not always. It could be someone very familiar with the product, 
but not necessarily developing the product. 
>>
 

"This (information design reviewer) seems very close to the "content 
editor"/writer process discussed in Dan's missive."

>>
Right again. I hesitate to use the term content editor for this role, as editing 
implies a review-and-feedback kind of a situation. The information design 
reviewer is much more interactive, more of a review-discuss-develop kind of a 
role. Nevertheless, in principle and spirit the role is close to that described 
by Dan. 
>>
 
"Greg's quip (about usability testing) 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?"

>>
At the moment the Sun team is only looking at doing testing on documentation 
that is going to be packaged with Sun systems. We will make our findings public. 
It might be best to put the documentation usability question to the team working 
with Arlo Rose. 

The reason you have to do documentation usability testing at a late stage is 
because the main things you are testing are ease-of-use and navigation. The book 
needs to be almost final before these things can be successfully tested. If 
there are major changes then the book goes back to the quality reviewer. The 
quality reviewer must make a judgement call as to whether the changes require 
editor involvement or not. Even if the editor needs to do another pass, it 
doesn't mean a full review as it's usually a question of small but significant 
changes that result from usability testing. 
>>
 
"FYI: The Gnome Style Guide will have a chapter on this (localization)."

>>
OK, I don't know if anyone has volunteered yet to supply information about 
writing for localization. If they haven't would it be OK with everyone if I 
supply something about this topic? 
>>
  

 (BTW, are you folks
> > from Sun on the GDP mailing list, or shall we keep you on the explicit
> > CC list?). 

>>
This was actually a point from Greg - well, we are on the gnome-doc-list alias, 
so you don't need to cc  us, unless you want to single us out...

Best, 

Pat