Re: Content of GNOME Developer's Guide

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

Ooops!  I somehow managed to send this directly to Todd without cc'ing
gnome-doc-list.  Here it is...

------------------------------

Todd Graham Lewis wrote:

> On Mon, 16 Nov 1998, John R Sheets wrote:
>
> > - Intro - What is GNOME & what does it offer; quick run-through
> > of terms & what the various software packages (e.g. auto*, CVS,
> > GTK+) do.
>
> Feel free to take this from the FAQ; Section 1 thereof has a pretty
> good introduction.

I'll definitely take a good long look at it.

>  BTW, what will the license be on the docs?
> Verbatim-only redistribution?  Unlimited, but with control over the
> title, ala the Artistic license?

Oh, gee, I don't know.  I suppose licensing is wide open at this point.  I had
assumed a GPL, but I have no overriding attachment to it (for docs anyway).
What would you suggest?

> > - Part One - Building GNOME Apps
> >   - Chapter 1: GnomeApp
> >   - Chapter 2: Menus
> >   - Chapter 3: Toolbars
> >   - Chapter 4: Controls (worthy of its own section???)
>
> Do initialization, popt, and the rest merit a separate section?

Initialization would probably go in Ch1.  Probably popt as well (not sure,
tho).

> > - Part Two - GNOME Components
> >   - Chapter 5: Common Dialogs
> >   - Chapter 6: Dialogs
> >   - Chapter 7: GnomeCanvas
> >   - Chapter 8: Applets (for Panel -- maybe in Appendix??)
>
> Sure.

Applets are kind of an odd man out with this book structure.  The appendix is
mostly reserved for non-GNOME topics (that's why Glib/GTK are there).  But
applets are definitely GNOME.  However, they are more of a specific
implementation than a core feature.  I dunno.  Just have to see.

> > - Part Three - The GNOME Framework
> >   - Chapter 9: Data Storage (XML, config, session mgt.)
>
> Whoa!  SM should get its own section.

You're right.  SM was a bit of a stretch in 'Data Storage'.

> >   - Chapter 10: Communication (libGnorba)
> >   - Chapter 11: Baboon (reusable components)
>
> Somewhere in here should be a general architectural overview of the
> component approach to programming, examples from the COM/OLE world, etc.

That would most likely fit in the Appendix (it's looking to be a rather long
appendix).

> > - Appendix
> >   - Installation (CVS, Autoconf/make)
> >   - Glib Primer (data structures, portability, modules)
> >   - GTK+ Primer
> >   - Internationalization
> >   - Sound
>
> I think that i18n and sound should go in Part 3.

Sound, yes; i18n, not sure.  Internationalization is more of a universal
feature.

> Also, I think that
> GLIB should be moved to the front, as programmers _have_ to understand
> it and its primacy in order to write good GNOME apps.

Agreed, it's very important, but not really GNOME.  Thus, the appendix.

> Some big components that I don't see mention of are:
>
>         - DnD

Yes, in Part 3, I would imagine.

>         - multiple languages (will the manual be C-only?)

Multiple programming languages?  Good point.  Maybe this would fit as a final
chapter in Part 3.

>         - OpenGL programming, important for games

Way off topic for GNOME, I think.

>         - imlib, which programmers most definitely should know about

Oops!  Definitely an oversight.

> This outline looks great!  Please don't take my suggestions to imply that
> you haven't done good work here, because you have.  What's the next step?
> I'm a big fan of lengthy outlines preceding the actual writing.

Well, I personally will have to do a lot of source-browsing and question-asking

so that I understand things deeply enough to write about them.  Research,
research, research.  I'll probably write as I go.

> Who is actually going to put in work on this project?  I am.

Glad to have you.  You've done a very nice job on the FAQ.  And also so far
with your comments here.

> We should
> take a tally of who we are so we know when everyone has had his say
> on stuff like this.

Yeah, I would like to know who is interested in what.  Get a headcount, so to
speak.

>  Or John, would you prefer to be the benevolent
> dictator?  I am fine with that, too; it means less work for the rest
> of us.  8^)

For now, I'll probably act as the Developer's Guide maintainer (assuming no
contentions (c: ).  I plan to do a lot of the writing, but by no means do I
want to do it all!  I think a potentially larger, broad-focused project like
this needs a central voice to hone in on the important points and provide a
higher level of consistency.  But as with any distributed project, the more
helpful voices, the better.  Think of me as a constructive filter.

> This should be fun!

Sure, if we do it right.  (c;

John