Re: library.gnome.org organization

[Frederic Peters <fpeters 0d be>]

Shaun McCance wrote:

> I've been writing down some notes on the organization
> of developer documents on library.gnome.org.  Some
> things are in odd places, and some pages just have
> too much stuff to be useful.

I totally agree, some things could be done just now as
I read this email but I will refrain on that and wait
for a grand master plan to come, or for the discussion
to settle, at least.


> * gnome-doc-make and gnome-doc-xslt don't really
> fit under Guides/GDP.  They're probably best off
> under Development Tools, alongside gtk-doc.  It
> might be good to have two sections on that page
> for applications and, um, other tools.

Agree.  And absolutely not difficult to move them.


> * We only have three documents for bindings: one
> for C++ and two for Python.  Surely there are more
> documents.  Additionally, these are buried deep in
> References.  Imagine you're a Python programmer.
> This is not an optimal way to find out how to use
> the Gnome platform.

The other really useful document about Python is the
PyGTK FAQ, it should really be included there.

And there is more to bindings than just C++ and
Python, including those other languages would be
useful too.


> * And on that note, References is way too long,
> and contains a lot of potential noise.  We have
> references there for stuff that isn't even in our
> release set.  I think it's great if we can provide
> this service to peripheral projects, but we don't
> want it to get in the way of our docs.

That would be my fault as I received requests against
library.gnome.org to include some documents (gnome-scan
being the latest one, added yesterday) about things
that are not approved yet.

Moving all of those to a "peripheral projects" page, 
or down the references page ?


> * The Deskbar module tutorial doesn't belong in
> Guides.  It's app-specific, and should be put with
> plugin manuals and such.

Ok.


> * Same with Nautilus Internals.

Ok.


> * I don't think we need a section for the Style
> Guide and GDP Handbook.  At least, I think they
> could be in the same section as the HIG.

They can be moved there.


> Here's a possible organization:
> 
> * Overviews, Guides, and Tutorials
> * Reference Manuals
>   - Platform
>   - C++ Bindings
>   - Python Bindings
>   - Desktop
>   - Other
>   - Specifications
> * Development Tools
> * Application Plugins and Internals
> 
> This isn't fully fleshed out.  Basically, I just
> want to ensure people can not only find what they
> want, but can also explore.  Thoughts?

>From home page to development to references to Python
docs may be a long way, perhaps the development page
could be modified to have direct links to subsections,

  Guides
  ------
  The guides provide the common practices used in code
  and interface design within the GNOME platform ...
  
  Reference Manuals
  -----------------
  The references contain the Application Programming
  Interface, list of functions, classes and ...
   - Platform
   - C++ Bindings
   - Python Bindings
   - Desktop
   - Other
   - Specifications

  Development Tools
  -----------------
  ...

  


        Frederic