Improving GNOME docs...

[Dave Neary <dneary free fr>]

...and getting them into print

Hi all,

I have talked to Shaun about this idea already, and Andy Oram (on CC)
has been very generous with his ideas up to this point.

I have a dream. That when an engineer from a software developer goes to
developer.gnome.org that he will be in awe of the quality and
organisation of our developer documentation. That ISDs will choose our
platform because it's so damn easy to get started. That a GNOME guide
for ISDs will become a bestseller, and will generate some money for the
foundation. That through working with a professional editor, the GNOME
docs team gets bigger and better.

And then let's start all over again with user documentation.

I would like to ask the foundation to budget some money for editing work
to generate a great guide to the GNOME platform for ISDs. And I would
like to have the result of that work get into print, and end up on the
coffee-table of everyone on this list.

So - that's my crazy idea. Thoughts?


Andy has previously written on the importance of getting a feedback loop
with community written documentation:
http://www.onlamp.com/pub/a/onlamp/2006/07/06/rethinking-community-documentation.html

He thinks that a first step in editing GNOME docs is to identify the
docs which we are going to use as a starting point, and then get some
quiz-type questions written which test understanding of the preceding
material. This will give us a baseline to measure the effectiveness of
the documentation, and allow us to focus our energy on where the docs
need improving/rewriting.

Here's an example quiz:
Docs: http://volity.org/docs/ui-guide/ui-guide-html/guide.html
Quiz: http://volity.org/docs/ui-guide/proposed_quiz.html

Our first job, then, is to come up with a list of documentation among
all the sources we have - from tutorials in the API docs, through the
ISD guide Shaun wrote and Zana Yuen's series of articles for RedHat
Magazine, old GNOME journal articles, tutorials, perhaps some bits of
GGAD - which we will use as the backbone of a great documentation set
for the GNOME platform.

Then for each document or set of documents, we come up with quizzes
testing the knowledge.

Then we put the quizzes in place, and provide some way to navigate
through the docs in a reasonably sane order.

Then we improve the docs that need improving until we're ready to
publish, with feedback from a professional editor (Andy) along the way.

Make no mistake, this is hard, it won't be done in 3 months, or even 6
months, and you will all be sick of the project before it gets finished.
But here's the end result:
http://developer.gnome.org/doc/GGAD/bookcover.png (strike out Havoc's
name, insert your own).

So - who's with me?

Cheers,
Dave.

-- 
David Neary
bolsh gnome org