Re: Improving GNOME docs...

[Joachim Noreiko <jnoreiko yahoo com>]

--- Dave Neary <dneary free fr> wrote:

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

Yup. library.gnome.org is the interface. The content
is existing application manuals and developer guides
-- and given that the last time I went looking for
developer guides I found loads of ancient GNOME 1
stuff, your proposal is rather timely :)

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

You'll need very pointy sticks.

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

You should look at and link to:

http://live.gnome.org/DeveloperGuides -- a list of the
documents we should have that several people including
Shaun worked on some time ago. 
I think it's easier to work with a set of documents
rather than a single great big monolith.

It would be great if we got the docs team up and
running, as we've been barely a handful for some time.
Which reminds me, I must do some more work on the
Handbook and Style guide so these ninja documentation
writers know what to do.

Send instant messages to your online friends http://uk.messenger.yahoo.com