Re: Developer Documentation Plan

[Gustavo Carneiro <gjcarneiro gmail com>]

I'm not volunteering any work (sorry), just one small comment.

The #1 gripe I have with current developer documentation is the way it disconnects the different language bindings.  For instance, python bindings authors have to copy-paste the C docs for a library, adapt to the python case.  Later a fix is applied to the docs for the C language and no one notices the python docs need a similar fix.  There's a lot of duplicated effort among different languages...

A good developer documentation should be described first in a language agnostic way, and then with small notes for each language explaining language specific issues.

On Mon, Mar 1, 2010 at 3:05 AM, Shaun McCance <shaunm gnome org> wrote:

Hi folks,

For the last week, I've been putting together a comprehensive
plan to overhaul and update our developer documentation.  My
plan is on live.gnome.org:

http://live.gnome.org/DocumentationProject/Planning/DeveloperDocs

Between user documentation, Mallard, Blip, Yelp, and the need
to take contracts to pay the bills, there is absolutely no way
I can lone-gun this.  But I will put everything I can into it
to ensure that we have top-notch developer documentation in
time for 3.0.

What I need is about six people to dive into this with me, and
commit to seeing it through.  You don't need to be a rockstar
hacker.  You just need to have a decent understanding of our
platform and the will to bug the experts on IRC.  I will help
you plan and write so that your work meets the needs of your
readers.

Comments, suggestions, and flames are absolutely welcome.  Our
community is what makes us who we are.


--
Shaun McCance
http://syllogist.net/

_______________________________________________
desktop-devel-list mailing list
desktop-devel-list gnome org
http://mail.gnome.org/mailman/listinfo/desktop-devel-list

--
Gustavo J. A. M. Carneiro
INESC Porto, UTM, WiN, http://win.inescporto.pt/gjc
"The universe is always one step beyond logic." -- Frank Herbert