Re: building GNOME vs writing docs

[Simos Xenitellis <simos74 gmx net>]

O/H Shaun McCance έγραψε:
> 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.
>   
Another option is to create a virtual machine suitable for VMWare 
Player. It should be easy for the developer and also for the 
documentation writer.
What you do here is you create such a virtual machine and let your 
technical writers run them with their VMWare Player.

Some links.
1. Free VMWare Player, available for Linux, Windows
http://www.vmware.com/products/player/
2. Community developed virtual machines list
http://www.vmware.com/vmtn/vm/community.html

The main advantages of a virtual machine over a Live CD are:
1. The developer can easily create it and customise by removing unneeded 
parts to make it small
2. No need to burn a CD
3. Faster to boot than CD as it resides on the hard disk
4. You can set the resolution by default to 800x600, which is friendly 
to screenshots.
5. You can even take screenshot of GDM.
6. Screenshots are saved either on the host OS or from within the 
virtual machine.

I am not affiliated with VMWare.

Hope this helps,
Simos