Re: Monolithic docs?

[John R Sheets <dusk smsi-roman com>]

Samuel Solon wrote:

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

Do you mean 'creating a monolithic developer document' or 'creating _only_ a
monolithic developer document'?  Generally speaking, the more accurate
documentation we have, the better.

I think we need to figure out the different forms and scopes the documentation
should take, so we can go about this in an organized fashion.

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

This sounds like a basic look-up reference system, where functions are names,
parameters are explained, and how the single functions are used is discussed.
Scope in reference documents is typically pretty narrow and focused.  You talk
about the function at hand, and generally don't go into the subtleties of using
it with other types of functions (e.g. using dialog functions in an application
with toolbars).  There's very little cross-pollenation.  This is very good for
the programmer with a specific task at hand, e.g. "How do I create a standard
GNOME dialog?"

But there's also the browsing approach, where the developer is looking for a
broader, more integrated view for more complex tasks, e.g. "How do I build a
Panel applet?".  They'll have to start ripping apart existing applets, which
hopefully have been written well.

Another difference between the two approaches is that the Reference Manuals are
typically accessed in random order, while the Developer's Guides are typically
read straight through, serially.

The reference section can probably be automated, for the most part, at least as
far as generating the basic framework (function calls, parameters, etc.).  The
higher-level approach (the Developer's Guide) will have to be hand-written and
agonized over.  IMHO, I think we should pursue both approaches in parallel.

> Gnome is a very dynamic system and probably won't settle down for awhile.

Not for at least a month, anyway.  (c:

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

As long as we stick to DocBook, both options will always be available (i.e.
postscript and HTML).

> 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

The above items would probably fit better in the Developer's Guide, along with
indepth descriptions of how they interact..

>       Overall description of "module"
>            glist
>            GtkCList

This could go in either.

>       Definition of structure
>            GdkEvent
>
>       Definition of routine call
>             gtk_clist_new
>
>       Description of "module"
>             Using GtkCList
>            Using glist

This would probably fit best in the Reference Guide, although I would expect to
see a fair amount of duplication.

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

References to external docs would be encouraged, as opposed to recreating the
wheel.

> To accomplish this we need to consider two issues: markup and help engine.
>
> 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.

This is moot, as we've standardized on DocBook.  And isn't the help engine an
HTML renderer?

> The last thing I would like to see is Gnome perpetrating another
> abomination like PDF

We're not in the business of inventing new standards, especially when perfectly
good ones already exist, e.g. DocBook, XML, CORBA, etc.

John