G2 Lessons Learned

[John Fleck <jfleck inkstain net>]

GNOME 2 lessons learned [1]

I've tried to jot down a few things I've learned doing GNOME2 docs,
things we did well and things where we need improvement. I'm not sure
how to do the math, so I'll just make a bold claim - I think GNOME 2
is the most thoroughly documented release we've ever done, so we're
definitely doing something right.

Package Responsibility

  Identifying individuals among us to take responsibility for the docs
  in each package worked. With (by my count) 54 docs installed with
  GNOME 2, there was no way any one person could have kept track of
  making sure all the bits got done. Parceling out ownership helped.

Style Guide

  I believe the Style Guide helped improve the quality of our
  documentation, but in the end, I didn't use it that much because I
  didn't write that much documentation for GNOME 2. I'd like feedback
  from others on its usability. This is especially important as we
  try to attract new volunteers.

Doctable

  We need to solve this problem. We floundered for a long time and
  lost energy and momentum because there were people wanting to do
  something but no clear way to figure out what needed to be done
  short of some sort of IRC ESP thing. In the past, the period of
  greatest momentum for the GDP was in the development of GNOME 1.2,
  when there was a ton of documentation to be written and you could
  just log onto the Doctable and easily find a task. The temporary
  Doctable helped noticeably, but really sucks.[2]

The Sysadmin Issue

  I'll only mention this problem briefly because I think it's my
  responsibility to solve it. When the Doctable went down, we had no
  way to get it back up because other people are in charge of the
  machine it sits on. When we wanted to post our docs on www.gnome.org
  - same thing. If we want to install Lampadas to solve the Doctable
  problem - same thing.

The Hacking Problem

  A number of the problems we faced in developing the GNOME 2
  infrastructure came about, in my view, because a bunch of us tried
  to design the thing, and we're not hackers. We are documenters, and
  as such ought to be good at defining the system's needs. But
  deciding how to design software to meet those needs has not been our
  strong suit. I don't mean here to diss Jonathan, who set up the API
  for us, or Mikael, who wrote Yelp. But the role played by both was
  more along the lines of cleaning up our messes rather than playing
  an integral role in the design from the beginning.

  This problem may already be solved by the miraculous arrival of
  Sander, who seems to have been assigned by Sun to essentially save
  our ass, and to whom we owe a great deal of beverage of some
  sort. The question now is whether we can continue to survive on the
  pity of Mikael and Sander, or to whether we need to recruit some
  hackers to our midst.

The New Blood Problem

  Time and again over the last six months we've gotten emails from
  newcomers anxious to to contribute, and I feel like we've not been
  very good at helping them find a way. We've been focused on the core
  infrastructure, which is not a great place to start newcomers, and
  with Sun doing so much of the primary documentation, there haven't
  been a lot of good opportunities. Ideas on how to change this are
  welcome.

Cheers,
John

[1] I love the scientists' tradition of identifying intellectual
helpers in a closing paragraph in their papers, so thanks for useful
discussion to Eric Baudais and my wife, Lissa Heineman, who is way
smarter about working with other people than I am.

[2] I'm allowed to say that. I wrote it.
-- 
John Fleck
jfleck inkstain net (h) jfleck abqjournal com (w)
http://www.inkstain.net http://www.abqjournal.com

"Sometimes, a diner is all about the mac and cheese." 
  - Zippy the Pinhead