Monolithic docs?

[Samuel Solon <ssolon usa net>]

Rather than addressing the outline presented I'd like to take a step back
and consider the structure of the proposed development docs. IMHO creating
a monolithic developer document would be a mistake. What is needed is a
flexible and modular system that can combine and cross-reference
information which may be created at different times, by different sources
(people *and* automagically from markup in the source listings) and have
different levels of existence (some items might be missing).

Gnome is a very dynamic system and probably won't settle down for awhile.
While I personally enjoy sitting down with printed documentation I doubt
most of the Gnome developer docs will be printed -- they will be accessed
online via a help system (when I say "online" here I mean using an
application).

The web has shown us that for online access the structuring of information
is important as the actual content. 

What I need to find out is (items following are examples):
      What categories of stuff is available?
           core libraries
	    ui libraries
  
      What functionality is available?
           ui components
           drag & drop

      Overall description of "module"
           glist
           GtkCList
 
      Definition of structure
           GdkEvent
           
      Definition of routine call
	    gtk_clist_new

      Description of "module"
	    Using GtkCList
           Using glist

As you can see from this list, I would like to have several different ways
of looking at an underlying document set. The documents should be
extensively cross-referenced and, in the online version, hyperlinked.

Some of the information that would need to be put in a developer doc
already exists in some form (Gtk docs, for example) and there is no reason
to either rewrite them or include a frozen version in a monolithic doc.

To accomplish this we need to consider two issues: markup and help engine.

Some sort of database engine will be needed to really make this system
work. If everyone were running a web server on their systems it would
simplify things. Perhaps a consisten naming scheme for documents might make
it possible to create cross-references in it's absence or perhaps a simple
search engine might make a good Gnome project.

The most important part to achieving such a help repository is coming up
with standards for marking up documents so they can be processed to produce
whatever format is needed for the help system. sgml is very flexible but
unless used consistently a lot of the value of the markup is lost.

I don't have all the answers -- I just wanted to encourage people to think
of documentation as more than just a linear series of words.

<rant>
The last thing I would like to see is Gnome perpetrating another
abomination like PDF (or Apple's DocReader before that). Looking at images
of 8.5x11 inch sheets of paper (complete with page numbers in space wasting
margins at the top and bottom of the "page") and having to scroll, scroll,
scroll, scroll, scroll (up, down, left, right) to see anything drives me
crazy!
</rant>

Sam Solon