Re: building GNOME vs writing docs

[Shaun McCance <shaunm gnome org>]

On Sun, 2006-02-05 at 12:07 +0000, Joachim Noreiko wrote:
> Our situation is that we need writers. We need to
> lower the barriers to entry, and one of them is
> expecting new doc writers to build themselves a
> complete GNOME from CVS before they can write
> documentation.
> 
> My experiences would suggest that expecting doc
> writers to build GNOME themselves isn't feasible.

[snipped insightful material for expediency]

> Here are my ideas for discussion, please add your own:
> 
> * provide binaries of apps that doc writers can
> download and run
> * ask people who can compile to write brief summaries
> of what's new, that doc writers can then clean up
> * make scripts that can build you a single app from
> CVS with one command

This is an unfortunate situation, to be sure.  Building
the latest and greatest from CVS, or even from the unstable
tarball releases, can be very difficult.  I'm a programmer,
and I maintain two of the modules in the desktop, and it
often trips me up.

*But* there's just no way around the fact that you need
to use the software in order to write documentation for
it.  I happen to work for a software company that has
in-house documentation writing, editing, and quality
assurance (some of the best in the industry, if I do
say so myself).  The tech writers are able to use the
latest because it's built for them.  It's not a whole
desktop environment, just an application, so it's much
easier to throw in a new binary and go.

So what can we do?  Having scripts to build a single app
just won't help that much.  We have scripts like jhbuild
for building.  But then, building a single app isn't even
all that difficult, if it's really all you need.  What
makes things difficult is that we make additions to the
platform, and apps then depend on those additions.  So
you've got to resolve the dependencies.

Providing binaries sure would be nice.  On more than one
occasion, people have tried to revive the Gnome Packaging
Project.  It's a worthy goal, but it's so damn difficult
because of all the disparate distros.

You mention asking developers to write brief "what's new"
synopses for our writers.  I think this is a wonderful
idea, absolutely great.  I've thought about it before,
and I think it would be great to *require* it of all the
desktop modules at feature freeze.  But it's not enough.
You really need to use stuff to document it well.

One possible solution is to provide Live CDs at every
unstable point release.  Doing so would undoubtedly
help the bug hunting efforts as well.  But it's a huge
undertaking.

--
Shaun