Developer Accessibility

EvoAqua (temporary vanity name for my mail speech-notification project) will probably be on hold for a little while.  I was going to integrate it into Evolution as an EPlugin, but besides being terribly ugly, they don't see to export a message's subject or sender information.  (Bug 588843.)  A better solution might be available soon that involves becoming a registrar that listens to DBus for mail notifications from more apps than just Evolution.  See http://live.gnome.org/Evolution/Metadata for more information.  It's on hold because, for that metadata, an EPlugin was written for tracker that will sit in Evolution to export it.  Then, I can listen to and grab it and do with it what I will.   Yay.


I'll note that documentation is a bit frustrating.  Everyone agrees that it needs to be better and that there needs to be more of it.  In Open Source, I'm welcome to jump in and help.  However, I and most other people already have many time sinks, and documentation is never as trivial to write as some calls for it make it sound.  You don't want to write ill-informed documentation.  That just doesn't help that much.  Trying to figure out how to write a simple EPlugin was painful, because I had to read a somewhat "comprehensive" though at times incomplete manual to EPlugin: http://projects.gnome.org/evolution/developer-doc/eplugin/.  It leaves me dangling on the edge of a bunch of theories that build up and cram up in my brain, trying to find concrete instantiation in an example to see how they actually apply.  In the end, it was useful, but it felt like it could have been much simpler.  I recall recently following the also-incomplete Pidgin documentation for writing a plug-in and having a much more pleasant experience.


I know I should also look at how other plugins are written, but they of course end up being rather large making it difficult to separate out the parts that are actually relevant to me.  In the end, it feels like I should learn much more about a system than I should need to to write a relatively small 100 line plugin.  Understanding the system I'm writing in is important, but some documentation and examples end up making that understanding much more expensive than it needs to be.


Official DBus GLib documentation is also incomplete.  Examples of usage online was somewhat helpful, but it largely pales in comparison to the informative capacity of something like Java's documentation.


So, I know it's expensive for the developer to invest a lot of time into the documentation; especially when they don't know how much of it will be used.  However, you have to wonder how many contributions or users of a framework are lost to people feeling put off by the guess-work they have to do.  I don't have a difficult time trying to think of why Maemo would switch toolkits (a massive change, isn't it?) from GTK+ to Qt.  (Though, I'm sure Hildon's redundancies didn't help.)  I cringe everytime I see people advertise certain frameworks or toolkits for other developers to come and use.  Yes, I like these very systems that I complain about right now, but their accessibility (by developers, not a11y) and polish are not yet something I'd want to market.  I hope it's not something systemic to Open Source.  Ugh.