Re: Improving GNOME docs...

[Don Scorgie <DonScorgie Blueyonder co uk>]

Hi Dave,

This all sounds brilliant!  More replies inline ;)

On Tue, 2006-10-17 at 15:50 +0200, Dave Neary wrote:
> ...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.

library.gnome.org?  Currently being worked on.  It would be a good place
to start (I believe there's going to be a "developer" section for e.g.
the gtk+ tutorial, API references etc.).

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

As part of Project Mallard (tm), a lot of the user docs would be
rewritten (hopefully) in a more user-friendly form.  If we could
integrate that effort with this...

> 
> 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?

I like the idea.  At the moment, the docs team is pretty understaffed
and under-equipped though.  Concentrating on developer docs in the first
instance would be a really good idea.  Though, I don't know where all
the people would come from.

While this dev doc stuff is going on, Project Mallard (tm) and
associated techs [1] can begin to be put in place for when the user docs
stuff can begin.

> 
> 
> 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?

I can help.  Despite my (many) other projects.  I'm not the greatest
writer in the world (you should read my thesis sometime :), but I'm
capable of writing at least first draft type stuff and testing /
proof-reading / helping answer technical questions.

I'd love to see a definitive "This is how to develop for GNOME and make
it integrate well" type resource.  Its one of the things we're really
missing [2].  One thing I'd love to see is the project being
cross-language (i.e. section on python, c, c++ etc.), if possible.

Now all we need is a codename for the project [3].

Don
[1] Including online doc-team status page which will make life easier in
this regard.  Maybe integrate quizzes with this and / or lib.g.o?
[2] There are a few out there, but they all seem to be missing something
for me
[3] All projects should have codenames.  And a world domination step.
Though, that can come later.