Re: Proposal for GNOME Developers' Guide

[Federico Mena Quintero <federico nuclecu unam mx>]

>  Here's my first pass at the overall structure for a GNOME
>  Developer's Guide documentation suite.  It's in a pretty lean
>  DocBook format (it won't parse properly, due to incomplete tag
>  sections, e.g. missing sections in the chapter blocks).  At this
>  point, I'm posting it more for debate over the content, than for
>  markup evaluation (though I'm happy to receive comments on
>  either). I am aware that it's incomplete, and left it that way
>  deliberately to make it easier to read.
>  
>  The intent of the dev-guide is to provide developers with
>  discussions and tutorials of how the internals of the GNOME
>  code-base works and interacts.  It would be more free-form,
>  organized by concept, as opposed to file/directory structure.  It
>  would be a supplement to the auto-generated API reference docs
>  that Scott Wimer has been working on.

I kind of like your proposed structure, in that it groups things by
subject or concept instead of by the directory structure of the
development libraries.  As people have already said, the front
end/back end division for gnome-libs is not very clear, but that is
not an issue.

I am a bit confused about your "Inside GNOME Applications" book.  Is
it intended to contain documentation on each program's internals and
how to extend them using the Baboon components they define?  I.e. if
Gnumeric provides a spreadsheet component, would the book describe how
to use it?

If that is the case, I would prefer to have a separate book for each
application -- this is just an organizational issue.

I would appreciate it if you could look into how to make it easy to
integrate all the documentation together, as far as the different
modules are concerned.  The way I am imagining it is that a toplevel
developer's documentation module would contain the basic bookset
information (the "set" tag).  However, I have no idea of how to plug
in the different parts of the documentation if they come from
different cvs modules.  I.e., how would Gnumeric or Gnomecal integrate
their own developer's docs into the main framework?  I don't know what
is the usual practice for dealing with this in DocBook.

  Federico