Re: Contribution of Sun documentation team to the GDP.

[Patrick Costello <Patrick Costello Sun COM>]

Mark McLoughlin wrote:
> 
> 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

That's not what I'm saying at all. What I'm saying is that it is counter
productive to put back into cvs jobs that are incomplete, in development,
all over the place, ragged and not ready to be included in a build. That is
analogous to putting back software that you can't build into a working
application for testing. Sorry. I'm not going back on that. As soon as a
writer has progressed a job to the level where there is sufficient correct
information for people to review, that's when the job should be made public
for review. I'm completely in agreement for review level drafts to go back
to cvs, visible to everybody who is interested. Oh, and "review level" does
not mean "completed". There are various levels of review drafts throughout
the development of a job. Check out the GDSG. 



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

When did I ever say that? What I said was that incomplete works in cvs had
caused spurious bug reports to come my way. I said nothing about bug
reports being bad and need to be avoided. On the contrary, we have lists of
>>hundreds<< of bugs that we - the Sun team - have picked up in Bugzilla and the Sun internal bug tracking system. That includes bugs that we have fixed for documentation, and bugs that we have logged with developers in respect to functionality. What is bad and to be avoided are spurious bug reports caused by missing information that is deliberately missing. Please do not misconstrue my words in this way. 

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

This is completely spurious. I thought I'd dealt with the "closed doors"
issue. I am not suggesting "putting back" "complete work" that has been
developed behind "closed doors". I am suggesting "putting back" works in
progress at sensible review stages. These review stages are well-defined
and regular. See the GDSG. Anything else will lead to confusion. And
spurious bug reports.
 

> 
>         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 implication being that the Sun team don't issue our works-in-progress
to everybody? Sorry, not true. Just that we don't issue our
works-in-progress every day, as you seem to be suggesting. 

I have run out of steam on this "closed doors" topic. I really have. Does
anyone else want to say something, one way or the other? 

Pat