Re: Contribution of Sun documentation team to the GDP.

[Mark McLoughlin <mark skynet ie>]

Hi Pat,

On Tue, 2004-04-06 at 11:01, Patrick Costello wrote:

> >         What I'd really like to see is a full, open and frank discussion on
> > figuring out a documentation development process that allows:
> > 
> >   + You guys to largely work from JDS yet still have your work be
> >     generally useful to the community.
> 
> We will put our JDS documentation back to the community, and this
> documentation could be useful for inclusion into future GNOME Desktop
> releases. But someone else will have to tailor our documentation to suit
> community needs.

	I think what's important here is that we figure out an optimal process
whereby your work is still useful to the community and vice versa. Its
clear that we're going to have (at least) two versions of documentation
(stock GNOME and JDS), but its important that community docs writers and
Sun docs writers are sharing the overall burden.

	Figuring out how to efficiently maintain those two separate versions is
going to be tough to figure out. I'm just a hacker and I'm not
immediately seeing why the problem is terribly different from the
problem that we hackers face with vendor-specific patches. I mean, the
very reason this problem has come about is Sun specific patches to the
code - it would be nice if the docs problem could be fixed by Sun
specific patches to the docs :-)
	
	Every time I think about the problem, the "ideal solution" I come up
with is:

  + Write the docs in vi/emacs/gedit - nothing which generates the XML
  + Work directly on CVS HEAD when working on the latest community 
    versions
  + When working on the Sun specific version, keep the stock community 
    version "pristine" and maintain your modifications as patches 
    created with "diff" which gets applied when building the package.

	But that's just my warped hacker brain. Next thing I'll be suggesting
the artists use PNG diffs rather than icon themes :-)

	That process probably wouldn't work for you guys. However, such a
process does have all the desirable properties I mentioned in my
previous email.

	Someone (in the community) who understands the docs writing process
needs to take this on and lead the task of working with you guys to
figure out a solution, in my opinion.

> >   + Your work to be regularly updated in its final location in CVS, even
> >     if it is unfinished/un-reviewed (works-in-progress in CVS is a good
> >     thing)
> 
> 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".

	Keeping the very, very latest versions of your work in CVS makes
collaborating with others much easier.

> >   + A greater level of communication and co-operation between everyone
> >     in the documentation project and hopefully a community atmosphere
> >     that would encourage more people to get involved
> > 
> 
> No amount of communication will alter the fact that we don't have enough
> resources in the Sun team to continue doing both Sun work and community
> work. No amount of cooperation will alter the version gap between Sun
> releases and community releases. No amount of community atmosphere will
> alter the design divergence between the Sun Desktop and the community
> Desktop. These are the things that are putting a strain on our small,
> overworked team. 

	Its very important for you guys to realise that *this isn't about you*.
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.

	The only undertaking you should feel you need to make is that while
stepping back from this role you won't hinder others from taking it
over. After that, anything you do is a bonus - in the same way that
*any* contribution to the project is a bonus.

Cheers,
Mark.