Re: Contribution of Sun documentation team to the GDP.

[Mark McLoughlin <mark skynet ie>]

Hi Pat,

On Wed, 2004-04-14 at 10:00, Patrick Costello wrote:

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

	I think you're dismissing the idea without really trying to understand
why we think this would be a good idea.

	Essentially, having the very, very latest version of any open-source
work available for the rest of the community to try out, contribute to,
comment on, file bugs against etc. is the tried and tested best practise
for open source development. 

	You are effectively saying here that

  1) We should try to limit the exposure of in-progress works to a much 
     smaller subset of the community than our large testing community

  2) Bug reports about docs are bad and to be avoided

	Any open source project which does its work mostly behind closed doors
and then "puts back" that almost complete work to the community is in
trouble. There is no scope for others to participate in the project
because the feel alienated and out of the loop with regards to the
latest progress of the project.

	The large body of people who would be exposed to your work-in-progress
documentation is not something to be avoided. It is something to be
embraced.

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

	Some points on this:

  +  You need to differentiate between "users" with "testers". Of course
     we don't want unfinished docs being shipped to our "users" - in 
     exactly the same way we don't want the software to crash for our 
     "users". But that's what the testing community is for.

  + A healthy documentation community would ensure that releasing
    incomplete docs would be something very rare and would get fixed
    quickly in the next release (e.g. 2.6.1 is only a month after 2.6.0)

  + I think the "cheap shot" risk we're running now - i.e. that the docs
    refer to an older version of the software or include documentation 
    for features (e.g. JDS features) that don't actually exist in the 
    software - is just as large a risk.

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

	Bug reports are a sign of a healthy testing community. If I stopped
getting bug reports for gnome-panel I would assume that people had
stopped bothering to test the panel rather than assuming there are no
bugs in the software.

	You also don't have to fix all the bugs yourself. Let others help out
and fix the bugs, act as a mentor to those trying to help out and
generally try to encourage more people to get involved.

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

	These are problems with your authoring process. These are problems we
(hopefully) could help you guys with if we only knew exactly what your
authoring process is. Remember, the goal here has to be to get more
authors are involved, so there are plenty of people out there who are
interested in making the authoring process easier.

	The ideal situation here is that you would have an authoring tool that
directly edits your cvs checkout so that committing back to cvs would be
a natural and straightforward part of your authoring process rather than
a time-consuming task.

Cheers,
Mark.