Re: Contribution of Sun documentation team to the GDP.

[Patrick Costello <Patrick Costello Sun COM>]

Telsa Gwynne wrote:
> 
> On Tue, Apr 13, 2004 at 08:47:18PM +0100 or thereabouts, Mark McLoughlin wrote:
> > Hi Pat,
> > > Our standard process is to put back drafts at each review stage.
> >
> >       Rather than committing changes back at each review stage, I'd suggest
> > that changes should be committed more or less as soon as they have been
> > made. There is no problem, in my mind, with docs in the development
> > releases containing something like "FIXME: this bit needs to be finished
> > off".
> 
> For the record, my gtop docs contained about five FIXMEs and were
> shipped like that in several distros. (Other distros managed
> somehow to truncate it and ship only the first third or so. I
> never figured out how.)
> 
> Over all the months (maybe a year or more) in which it was shipped
> like that I was awaiting the complaints, comments and perhaps even
> the explanations which would help finish them. I received one bug
> report about visible FIXMEs in the thing.
> 
> It came from a sun.com address :)
> 
> Which is a long-winded intro to saying that I agree with Mark.
> We are rather better about grepping for FIXMEs these days anyway.
> But having them in CVS helps a lot.
> 
> > Of course it is understandable that you guys don't have the time to
> > continue what you were doing. People's constantly changing ability to
> > commit time to a project is something that every healthy open source
> > project must have (and does have) the ability to adapt to.
> 
> Agreed, again.
> 
> Telsa


Well I think that putting back incomplete WIP drafts is a terrible idea,
for the following reasons:

- The WIP draft might get forgotten or overlooked. There is a potential for
user confusion or embarassement or the GNOME project as a whole. While we
are still trying to position the Desktop as a professional alternative to
commercial Desktops, we should strive to eliminate any loopholes that could
possibly give opponents to free software a cheap shot. Incomplete WIP
drafts in a final release would be a classic cheap shot. 

-  Notwithstanding Telsa's experience, I have received numerous spurious
bug reports from the Sun internal bugging tracking system regarding
missing, incomplete, or inaccurate information chunks in GNOME
documentation. Most of the time these bug reports arose from documentation
for unsupported or other community-supplied documentation, but I still had
to spend the time checking up on the bugs. I don't recall any bug reports
of this nature arising from the Sun supplied documentation, because of the
process we follow in putting back ready-to-view drafts. Therefore, from my
point of view, the putting back of WIP drafts leads to spurious bug reports
and consequent lost time for me, not to mention the Sun testing and quality
engineers who spend time checking up on Help. 

- Whereas a community author might be dealing with one or two manuals, we
are dealing with dozens on the go at the same time. Putting back to CVS is
not time-consuming for one or two jobs, but becomes so for a large number
of simultaneous jobs. 

- Some of our stuff is created in sgml. What should we do? Convert to xml
every day, which is a time-consuming process each time, or put back in
sgml, which is still usable for community authors but requires more effort
on their part. 

Putting back regular review drafts is an acceptable compromise, will reduce
bug reports for finished releases, and is do-able from our perspective.

Pat

-