Re: GNOME 2.8 focus

[Shaun McCance <shaunm gnome org>]

On Fri, 2004-03-26 at 01:54, Marius Andreiana wrote:
> Hi
> What's the GNOME 2.8 focus?
> 
> Your opinion about these?
> 
> * developers - make it easy and fast to develop gnome apps. What's Glade
> 3 status? Monodevelop, Eclipse, Anjunta should work nice. 
> Include C API in Monodoc for easy browsing (now one has to use the HTML
> docs for each separate library. Monodoc has all in one, allows index and
> search)

Better developer docs would certainly help here.  High-level guides are
critical to making it easier to get started with the platform.  An API
reference is only useful when you already know what you're doing.  The
GStreamer Application Development Manual and the GTK+ Tutorial are good
examples of high-level documentation.

Even the API references need work for quite a few libraries.  In my
opinion, a new public symbol shouldn't even go into CVS without a blurb
saying what it's for.  We're not talking a big elaborate explanation
here.  People can and do go through the libraries improving the docs. 
But those people have to be able to figure things out to document them. 
If Joe Docs is going through libfoo and sees an undocumented

void   foo_frobnicate_my_ass   (void)

he's just going to shake his head and move on.  Even just a little blurb
can give Joe Docs an idea of what's going on and allow him to experiment
with things and ask intelligent questions so he can write more docs.

Also, our platform moves pretty quickly, and we have a lot of deprecated
stuff hanging around.  In an API reference (but not in high-level docs),
it's necessary to keep these documented.  But that doesn't mean we have
to let the deprecated stuff mingle with the non-deprecated stuff.  Shove
it off in an appendix or something.  In the general case, it just gets
in the way.

So if we want a focus, I propose we have a concerted effort to have, at
the very least, complete API references for every library, whether in
the desktop or the developer platform.  Every library should use gtk-doc
or some other system, and every public symbol should be documented.  And
if we can get people to write some high-level docs, all the better!

Beyond that, people can and should use these same systems to document
their APIs inside their programs.  (As in, "hey, what the hell is this
YelpPager class?")  This lowers the barrier for new developers to start
hacking those programs.

--
Shaun