Re: Improving GNOME docs...

[Dave Neary <dneary free fr>]

Hi,

Don Scorgie wrote:
> 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.).

I haven't yet seen the results of library.gnome.org, I'm afraid. The
plan is not to re-write all the devel docs, it's to organise them, allow
reader comments, make them searchable, etc, right? A kind of MSDN for GNOME?

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

We'll turn into the Ninja Docs Team, springing out of the darkness to
force developers to document their APIs and blog their discoveries.

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

I suggest this as a starting point:
http://developer.gnome.org/doc/guides/platform-overview/platform-overview.html

Imagine this as the table of contents & chapter 1 of the book. One thing
we could do is to gather the existing docs (tutorials, API docs,
chapters of online books, etc) for each topic, rate them among ourselves
in terms of quality, get some developers to look at them to check
accuracy, and try to build up a structure of docs like that which will
form the basis for a book.

We should start this in the wiki: http://live.gnome.org/CodenameGraphite

I have created a very rough initial version, where I link to a bunch of
stuff, and there's a bunch of stuff that has nothing linking to it, and
more subjects that I didn't include links for. A good first step would
be fore someone to look at this, and tell me if it's a decent way to go.
If so, we can start with phase 2 - separating the wheat from the chaff.

Obviously, docs included here should be freely reusable in a book - but
we know most of the authors and can probably get permission if there's a
great doc linked on gnome.org that we can't reuse freely.

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

Codename Libron (Libre + libro = book)
Codename Nyx (God of co-operation)
Codename Shoeshine
Codename Graphite (a bit of pressure and time, and we'll end up with a
diamond, plus the whole pencil thing)
Codename Nyf (similar idea - diamonds are often found coated in an
opaque, gum-like skin called nyf)

I liked Graphite best, and chose that as the initial name for the page.
It's black & greasy, and you can use it to darken your face for those
ninja attacks.

Cheers,
Dave.

-- 
David Neary
bolsh gnome org