Re: Lowering the barrier (was: Re: build systems)

["Elijah Newren" <newren gmail com>]

On Nov 10, 2007 7:41 AM, Emmanuele Bassi <ebassi gmail com> wrote:
> On Sat, 2007-11-10 at 15:06 +0100, Mikkel Kamstrup Erlandsen wrote:
>
> >  * GObjects are conceptually difficult when you have standard
> > knowledge of C# or Java
>
> you know you don't have to use GObjects with C, right? you can write
> native C# and Java applications.

...or python or perl or c++.  I'm an example of someone who never
bothered learning much of anything about GObject, yet have still done
a fair number of contributions.  In fact, my contributions have mostly
been to existing apps/libraries written in C (just avoiding any parts
of the code dealing with GObject).

> >  * Autotools are exceptionally hard to work with
>
> they are not "exceptionally hard". they require documentation, and we

I'll agree with Mikkel, here.  They are exceptionally hard.  And I
think "getting started" tutorials which include info on autotools do a
disservice to would-be contributors.  My eyes glazed over lots of
times trying to read such documentation and it definitely hindered my
becoming a contributor.  I eventually figured out that I didn't need
to bother with that mess in most cases (someone else will always
contribute auto-tooling patches), though I did eventually learn a fair
amount and have fixed various issues here and there.

> >  * Some parts of the Gnome API are just plain hard to use. Ever tried
> > implementing a panle applet? Wonder why we have to many apps using
> > tray icons?
>
> from a cursory glance in my chat logs of #gnome on irc.gimp.org and
> gtk-list archives it seems that everybody start with panel applets; I

Not me!  But I agree with the rest of your comments.

> >  * General API docs are not as good as they could be. Compare QT4
> > documentation with GLib to see the point.
>
> maintainers in glib and gtk+ have been incredibly responsive in pushing
> documentation patches; people rarely have to wait a day for a commit
> authorisation (insert kudos to Matthias and Tim here). we need more
> people fixing the documentation and attaching patches to bugzilla. it's
> quite easy.

I agree with Emmanuele here, though I have some extra comments about
helping out with developer documentation:

I thought it'd only take me a couple weeks of spare time to get up to
speed and start contributing way back when I was getting started.  I
was off by at least an order of magnitude, in large part due to
lacking documentation.  Lacking either because it didn't exist, or
because it was inappropriate for beginners (despite the fact that
everyone would point beginners at these documents).  The documents
that did exist would often waste my time on stuff like autotools,
intltool, popt, gobject, compiling from cvs, etc.  Just give me enough
info to get started on creating *something*!  (I can learn how to
generalize the thing later to handle a11y, i18n, u7y, a1t, portable
building, source control...but let me start by being able to create
something simple I can see now!)  At some point when I (and others)
were complaining about this, Luis suggested that I write such a
document.  Sure, it took me a while to be able to do so as I had to
learn some stuff, and the document I wrote was pretty simple and far
from complete (http://www.gnome.org/~newren/tutorials/developing-with-gnome/,
and is now a little bit out of date too) but I had LOTS of people
thanking me for writing it and saying that it was VERY helpful to
them.

Someone else needs to pick up the torch and write more.  But please
don't waste the time of beginners at the start by making them learn
every possible technology that might be used.  Help them make
something simple.  Then extend it a bit.  Let all the general stuff
come later.  Putting it up front just means  they'll either give up or
take *far* longer to become a useful contributor.

> >  * It is sometimes hard to grok how an application or lib is
> > internally structured. While
> > http://library.gnome.org/devel/platform-overview/stable/ goes some of
> > the way describing the platform as a whole, the internal structure of
> > apps and libs are sometimes elusive.
>
> you have the code. if the application/library is complicated pester the
> maintainers for explanations and submit a patch documenting the nasty
> bits. or removing them, if possible.

I had the same difficulty as Mikkel, and believe that several people
do.  After learning metacity, I added some documents to try to fix
this.  See

http://svn.gnome.org/viewvc/metacity/trunk/HACKING?view=markup
http://svn.gnome.org/viewvc/metacity/trunk/doc/code-overview.txt?view=markup

Comments I've heard since that time seem to suggest that these
documents have been very helpful for others wanting to contribute.  I
meant to add such documentation for libwnck and bugzilla as well; I
wrote a little bit of information for both (though I only committed
the libwnck stuff; and lost my preliminary bugzilla docs at some
point).  It'd be great to find other volunteers willing to learn a
module and write up such documentation.


Just my $0.02,
Elijah