[Fwd: Re: [Fwd: Communication]]

[Eric Baudais <baudais kkpsi org>]

-----Forwarded Message-----

> From: Eric Baudais <baudais kkpsi org>
> To: Pat Costello <patrickcostello eircom net>
> Cc: Eugene O'Connor <Eugene Oconnor Sun COM>, Irene Ryan <irene ryan Sun COM>, john sheehan sun com, Pat Costello <Patrick Costello Sun COM>
> Subject: Re: [Fwd: Communication]
> Date: 01 Sep 2002 21:25:17 -0500
> 
> Pat-
> 
> I have likewise been disturbed by your response to my analysis of the
> problems I see within the sun doc team and proposals to remedy the
> problems.  I do not wish this to degrade into a flame war, but I feel
> strongly the sun doc team can improve their communication with the gnome
> community.  Since you do not feel the need to talk about this publicly I
> have responded to your insightful email privately.
> 
> On Fri, 2002-08-30 at 15:12, Pat Costello wrote:
> > Eric,
> > 
> > See my responses to your mail. Our whole team is very disturbed by your 
> > assertions and allegations. I can only conclude that you have 
> > misinterpreted our best intentions. Your mail seems like an unwarranted 
> > attack.   If you feel that you have valid points about the Sun 
> > documentation team contribution to GNOME, and want to take this 
> > discussion further, then I suggest that you include other active members 
> > of the community such as John Fleck, Sasha Kirillov, Dan Mueth, Jeff 
> > Waugh. As always, we are happy to discuss our role and contribution with 
> > the community.
> > 
> > Pat
> > 
> > > 
> > >
> > >
> > > ------------------------------------------------------------------------
> > >
> > > Subject:
> > >
> > > Communication
> > > From:
> > >
> > > Eric Baudais <baudais kkpsi org>
> > > Date:
> > >
> > > 29 Aug 2002 23:31:30 -0500
> > > To:
> > >
> > > Pat Costello <Patrick Costello sun com>, Irene Ryan 
> > > <irene ryan sun com>, "Eugene O'Connor" <Eugene Oconnor sun com>, 
> > > john sheehan sun com
> > >
> > >
> > >Sun Doc Team-
> > >
> > >During your involvement in the GNOME project I feel there have been
> > >times when the intentions and plans of the Sun doc team have not been
> > >communicated fully to the GNOME community.  When the Sun doc team
> > >started you said you would document X applications.  This is fine, even
> > >if you stepped on some people's toes.  
> > >
> > Stepped on people's toes? Really? We have made a huge effort to do the 
> > right thing. We have always made a point of asking previous authors if 
> > they minded us revising their documents. We have always discussed 
> > information design proposals with the community. We have always floated 
> > our ideas before going ahead with proposals. You can hardly classify 
> > this behavior as stepping on toes.
> 
> As the maintainer and author of the gedit manual for GNOME 1.4 I do feel
> as though my "toes were stepped on."  I do realize in the beginning the
> sun doc team posted a list of applications you were going to document,
> but I feel it was with a take or leave it attitude.  I never received an
> email from the sun doc team personally stating they were going to
> document gedit.  When the sun doc team presented Paolo with completed
> documentation I felt my efforts to continue to revise the gedit
> documentation were better spent elsewhere for the good of the GNOME
> community.
> 
> Regardless of my personal experiences I believe the sun doc team can
> improve their communication with the GNOME community.  I will try to
> clarify through examples and suggestions the problems I see with
> communication between the sun doc team and the community along with
> possible solutions.
> 
> > >We took into account you were new
> > >to the GNOME community.  In July I thought Eugene was doing a good job
> > >communicating your plans, but in a month and a half there has been no
> > >communication.
> > >
> > What do you mean by "We"? Are you formally expressing the views of the 
> > GNOME community?
> 
> I meant the GNOME community is tolerant with new contributors.  I have
> never claimed to voice the opinions of the GNOME community.  I speak on
> my behalf and no one else.
> 
> > >The way the GNOME community communicates with each other is through the
> > >mailing lists.  Typically each project has one "leader" but they just
> > >organize the efforts of the mailing list with other projects and
> > >maintainers in GNOME.  Yet the mailing list is the main form of
> > >communication within the project.  In the past I have written up IRC log
> > >summaries when important discussions occur in #docs and emailed them to
> > >the mailing list.  All announcements are done through the mailing
> > >lists.  It is the medium of choice in the GNOME project.
> > >
> > The mailing list seems to have been very quiet recently. There seems to 
> > be a general lack of traffic on the gnome doc list. Maybe there needs to 
> > be a discussion about how things work.
> 
> The mailing list has been anything but quiet.  In the month of August
> there were 65 emails which is quite active for solely a documentation
> list.  The gnome-doc-list has always been a low volume list, but this
> does not indicate the community is not utilizing the list.  Yet I do
> feel the sun doc team has underused this valuable resource.  The sun doc
> team only responded to Trevor's email during the month of August.  I
> have to assume the sun doc team is working on some documentation.  Yet I
> have no idea what you are doing.  It would be nice to give the community
> a heads up on what you are planning to work on.  The gnome doc list is
> also open for the sun doc team to ask questions about technical topics
> related to documentation.  I cannot believe in 4 months the sun doc team
> has mastered the intricacies of DocBook and the infrastructure for GNOME
> 2.  The responses you receive from the doc list might prove more
> beneficial than the answers Glynn, Calum or other members of the Sun's
> GNOME team can provide.
> 
> >From the month of August I would like to give you an example of how the
> mailing list has been used to improve GNOME documentation.  On August 11
> Andrew Sobala asked if any documentation has been written on gnotski. 
> Chris Lyttle, the maintainer of the gnome-games documentation effort,
> informed Andrew that none was written.  I asked Chris later what has
> happened and Andrew has written the documentation along with a patch to
> add help buttons so the documentation can be accessed.  By free and open
> communication the doc list was used to prevent duplication of
> documentation efforts and allow people to work together in the
> community.
> 
> > >It has typically been the standard within the GDP to announce who is
> > >writing what documentation in order to avoid conflicts.  You will
> > >noticed I announced I was going to revise the GDP Handbook.  I announce
> > >each revision (cvs commit) of the Handbook.  When the Handbook is done I
> > >will announce it and contact our webmaster to publish it to the GDP
> > >website.  I do not see the sun doc team announcing any revisions of
> > >manuals.  I noticed a couple of days ago the sun doc team committed a
> > >large update to the User's Guide.  You should announce this so everyone
> > >can look at the changes made.  
> > >
> > Eugene did a routine bug fix update on the user guide. We didn't think 
> > there was a need to for a formal announcement.  Does each update require 
> > a formal announcement?  Maybe yes.  Maybe everyone should send out 
> > notifications every time they do an update. 
> 
> No.  A formal announcement to gnome-announce is not required for each
> update to the User's Guide.  A friendly email to inform the
> documentation community of the update is a good thing to do.  This will
> help the peer review process of the User's Guide because people with an
> interest in documentation will know when the documentation was updated. 
> I believe this improves communication within the community and awareness
> of other contributor's accomplishments.
> 
> > >I've heard from Glynn Foster that the sun
> > >doc team is planning to write a GNOME System Administrator's Guide and
> > >GNOME Developer's Guide.  Yet there has been no announcement of the sun
> > >doc team's intentions to do so.  If someone wrote a System
> > >Administrator's Guide they would have as much right to publish it as the
> > >official GNOME System Administrator's Guide as Sun does.
> > >
> > We are not sure if these books are going to be Solaris specific or GNOME 
> > generic. If they are going to be generic, then of course we will 
> > announce our intention to the community, as we have always done in the 
> > past. We have not even scoped out the requirement yet for these books. 
> > In the meantime, Sun is not stopping anyone else writing a GNOME System 
> > Administrator's Guide. As an independent company, Sun is perfectly 
> > entitled to these internal discussions without having to consult 
> > external parties.
> 
> The issue was not whether Sun was entitled to conduct internal
> discussions.  I was giving a specific example of the sun doc team's lack
> of utilizing the mailing lists.  I think it would be fine if the sun doc
> team emailed the doc list saying they were researching a GNOME
> developer's guide and system administrator's guide, but were unsure
> whether it was going to be Solaris specific or GNOME generic.  I believe
> you would receive encouragement to write the documentation GNOME
> generic.  Even if you did write solaris specific documentation guides,
> the community could benefit from reusing some of your ideas you imparted
> in the solaris specific documentation.
> 
> > >I feel at times the sun doc has pushed people out of writing
> > >documentation for GNOME.  I was planning to write the gedit docs for
> > >GNOME 2.  My plans were delayed because of some personal problems and
> > >when I come back to the project the sun doc team has announced one of
> > >the first docs they were going to write was for gedit.  I had written
> > >the mailbox applet docs and asked for editting comments from the list,
> > >which was not taken by the sun doc team in the doctable--.  The sun doc
> > >team whipped out a similar doc.  These were isolated occurrences, but
> > >give the impression the sun doc team is unwilling to use any community
> > >material and is only providing docs to the GNOME community on an as is
> > >basis rather than being lasting maintainers of the documentation.
> > >
> > We have always conducted an open discussion with everybody involved in 
> > writing manuals. For example, we contacted you about the mailbox and 
> > gedit documentation. The community did not have to use the Sun versions 
> > in those instances.
> 
> I did not state in this paragraph the sun doc team was not conducting
> open discussions.  I do feel the sun doc team's communications have been
> open, but also feel the sun doc team has not used the mailing lists, the
> main form of communication within the GNOME community, to their full
> potential.
> 
> I do feel the sun doc team does not accept community documentation.  If
> the documentation follows the GDSG you have said Sun would use the
> documentation.  However, I feel early on the Sun doc team gave a list of
> documentation which would be the GNOME desktop on Solaris and wanted to
> write all of the documentation instead of modifying community
> documentation.  My example of Irene providing a complete mailbox applet
> documentation supports this.  I do not believe she did anything wrong. 
> However, I feel it is a bit intimidating to provide the current
> maintainer of the documentation with a complete doc after they have
> worked to modified the original documentation.  If this is an isolated
> occurence I will not mention it further.
> 
> > >The solution to the communication problem is to be more open.  The sun
> > >doc team is very closed when it comes to discussing long term goals and
> > >plans.  Discussion on the mailing lists is encouraged.  
> > >
> > We cannot accept that the Sun documentation team is "very closed" in 
> > discussing long term goals and plans. This assertion is not true. 
> 
> What you can or cannot accept is up to you.  My feeling, along with
> other people I've discussed this with, is the sun doc team does not
> discuss its long term plans with the GNOME community.  More effective
> use of the gnome doc mailing list will help to change my opinion.
> 
> > >Especially long
> > >term planning of future goals.  Outline the sun doc team's strategy to
> > >help document GNOME and ask how this fits into other people's plans and
> > >opinions.  Collaboration with the community improves Sun documentation
> > >along with GNOME documentation.  
> > >
> > That's right. Just like we have done all along.
> 
> I have not seen the sun doc team's current plans for GNOME
> documentation.  The community is planning for GNOME 2.2, but the sun doc
> team is rather mute on the subject.  Granted there has not been any
> official communication on the doc list about GNOME 2.2 specifically, but
> future plans are being made like using Lampadas to provide a consistent
> documentation management system.
> 
> > >Respect other people's hard work and do
> > >not bulldoze them over by duplicating their work.  
> > >
> > Bulldoze? For a long time we put our output in a separate area of 
> > gnome/cvs, and put nothing into the mainstream cvs, for the simple 
> > reason that we did not want to foist our documentation on anybody. We 
> > were always willing to share what we did, and we are happy if what we do 
> > is accepted by the community. There is no coercion. We still hold true 
> > to that ethos. How have we bulldozed people?
> 
> I believe this strategy does not work with the GNOME community.  By
> putting documentation in obscure places in CVS you do not make your work
> visible.  It would be fine to place documentation in the "mainstream"
> CVS, but along with that needs to come communication from you on the
> lists about the documentation.  The GNOME community would not feel
> coerced if the sun doc team asked for comments on specific documentation
> you placed in CVS.
> 
> > >Since all the
> > >documentation is licensed under the FDL the sun doc team can take other
> > >people's documentation while the GNOME project benefits from Sun's
> > >documentation.  
> > >
> > As a commercial distributor with legallly-enforceable responsibilities, 
> > Sun can only include documentation that meets requirements for the 
> > following:
> >
> > - Translation
> > - Usability
> > - Accessiblity
> > 
> > The only way to ensure that documentation meets these requirements is to 
> > write the documentation according to the GNOME Documentation Style 
> > Guide. If other contributors provide manuals that comply with the GDSG, 
> > then Sun is willing to use that material.
> 
> Sun does not have many legally enforceable responsibilities.  All your
> documentation comes with the lofty guarantee none of the documentation
> is correct nor can we be held accountable if the documentation leads
> people astray.  You were instrumental is adding this to all GNOME
> documentation and did the community a good service I feel.
> 
> However, I feel all GNOME documentation should adhere to the standards
> set by the GDSG and the GDP Handbook.
> 
> > >Provide a lasting commitment to GNOME documentation. 
> > >The feeling right now is the sun doc team is only concerned with Sun's
> > >documentation of GNOME and not with GNOME documentation.  By not
> > >participating in discussions and waiting weeks to answer emails you give
> > >the impression the sun doc team is only concerned with writing Sun
> > >documentation.  It is just by happenstance the Sun managers let the sun
> > >doc team release the documentation to the GNOME community.
> > >
> > Every contributor has certain interests and does things that are 
> > important to them. Sun is no different from every other contributor in 
> > this regard.
> > 
> > I have no idea what you mean by happenstance. We have said from the very 
> > beginning that people can use our documentation if they want to, and 
> > only if they want to. We have said from the beginning that the community 
> > do not have to use our documentation. Everything we have done is above 
> > board, clear, and out in the open.
> 
> I should not say happenstance.  It is by the great work Calum, Gylnn,
> Jim, Bruce and other Sun people have been instrumental in showing Sun
> that contributing to GNOME is a good thing and can benefit both
> organizations.  These suggestions are provided in the good will these
> great people have fostered to improve the sun doc team's contribution to
> the community and avoid future misunderstandings.
> 
> Eric Baudais