Re: Contribution of Sun documentation team to the GDP.

[Shaun McCance <shaunm gnome org>]

Hi Pat,

I certainly don't want anybody to feel they're under any obligation to
do documentation work.  This is an open project, and people's roles will
naturally change over time.  Of course, it's generally polite for one to
be upfront about what one can do, which is exactly what you're doing.

On Tue, 2004-04-13 at 14:30 +0100, Patrick Costello wrote:
> Thanks for your understanding for the difficult decision we have had to
> reach. Just to be absolutely clear about our continued involvement in GNOME
> documentation, though, I'd like to make the following statements: 
> 
> - We are still interested in doing a limited number of Help manuals for the
> GNOME 2.8 Desktop and future releases, although nowhere near as many as we
> have done in the past. 

I understand that you guys have quite a bit of work you have to do for
Sun specifically, as do the writers at other companies involved in GNOME
documentation.  You've taken on much more than any other team I'm aware
of, and it doesn't surprise me that you'd want to scale back some.

Really, I think you can take the same approach as any other contributor.
If there's particular document you want to work on, volunteer for it.
The team is going to face some difficulties filling the roles for some
of the larger documents, but I'm confident we can manage.

[snip]

> - We will be ready to share our knowledge and experience with other
> contributors who take over jobs that we have worked on up to now. 

That would be great.  We do seem to get a lot of new people interested
in writing docs for us.  But, like programming, good tehcnical writing
isn't some trivial task anybody can pick up and do well overnight.

What I'd really like to do is have a concentrated review process before
we do stable releases.  I think your experience could be helpful here,
if you're interested.

> The six month cycle between major GNOME Desktop releases is fairly
> gruelling, so I think we had better set about re-assigning responsbilities
> for documentation right away. The first thing that we need to do, in my
> opinion, is sort out the planning. We should all be working from the same,
> agreed planning system. Personally, I don't care if this is the existing
> Doctable, or a more dynamic system such as Shaun indicated in January. 

Six months *is* gruelling, I agree.  If all goes well, we're looking at
about a one month time frame before I can do an automagic DocTable that
works well.  This all goes together with build tools I've been working
on.  This will require us to put a bit more structured metadata in the
documents, but that's generally a good idea anyway.

[snip]

> The one job that I think really needs an owner right away is the GNOME
> Desktop User Guide. This time around Brian Casey did a heroic job trying to
> document as much as possible of the new Nautilus functionality in time for
> the 2.6 release. However, due to the amount of work involved and the
> limited time, there were things that Brian didn't get around to doing. This
> would be the right place for someone to start work on to be sure that we
> have an up-to-date 2.8 user guide when release time rolls around. Brian can
> give some pointers about what still needs to be done. Not a job for someone
> new to technical writing or the GNOME Desktop, however. 

Yes, agreed.  For a lot of the smaller tasks, I think we can get some of
the eager new people to jump on.  But we should probably find a seasoned
writer in the community to take on the User Guide.  And we should do it
soon.  The User Guide is a big task.

There are, by the way, a few problems with the 2.6.0 User Guide that
should be addressed for 2.6.1.  It appears some JDS stuff slipped into
the community docs.  Can Brian or another of the Sun team address this
for 2.6.1, or should we try to find somebody else for that?

--
Shaun