Re: GNOME Development Network

[Alberto Ruiz <aruiz gnome org>]

Hi Thomas!

Thanks a lot for your offer to help, I'm CCing gtk-devel for the rest of the hackers to follow this conversation and making sure we don't duplicate any work ;-)

There are things you can help with along these lines. The first thing is, if you really want to help me, please spend some time learning django! I've been learning as I go, is not a big deal if you know pyhton already and I can certainly help. I have very limited time to work on this so I really need help with the core. You don't need to learn giraffe, I have that covered!

On a more high level point of view, I think the best way you can help is by putting together an API documentation review plan for the GNOME project. We can start small and we will certainly need help, but writing guidelines on how someone can review the docs would be nice! (This could be like the HIG for API documentation X-)

Now, before we do the guidelines we need to do some ground work to figure out what the most common quirks are, this means taking a library like GLib/GObject and going through it sctructure by structure, class by class and function by function, trying to figure out things like you mentioned (which functions should I use with this one, how do I get an object of class X from?)

We can start with GObject itself and move from there!

What do you think? Are you up for the task?

Cheers,

Alberto Ruiz

2012/2/16 Thomas H.P. Andersen <phomes gmail com>

Hi Alberto,

I just read your blog post. Really really cool stuff. I have been
wanting to do something along the same lines myself. I do some .net
programming at work and the online documentation and fine grained
examples there always leave me wishing for the same for gobject/gtk.

I have zero experience with django or giraffe but I would like to
contribute with actual content. That is, small per-method examples and
things like that.

Random thoughts and ideas I have had about documentation: (sorry for
just dumping my thoughts instead of patches)

1) Can useful information be extracted from the large corpus of code
using the api's. Things like:
 a) Highlight most used/popular methods for the class
 b) Group methods together by how frequently they are used together
on an object.
   E.g. for a GtkSpinner object the method gtk_spinner_start is often
called just after a gtk_widget_show.
   After the GtkBuilder constructor the first call is often
gtk_builder_add_from_file then often followed by
gtk_builder_connect_signals etc etc

2) Direct links to cgit web interface for code using the api.
Checking how other people use an api can help if the documentation was
not clear enough. A poor man's documentation example if you like. I
sometimes just grep another project (often gedit or epiphany) to check
for neat tricks with a specific class/method.

3) Direct link to the implementation
I often find myself digging in gtk/glib for api I am using. A direct
link to the implementation could be cool.

4) Was this this documentation helpful? 1-5 stars rating.

5) Use code examples as unit tests
Could help to make sure the examples are still correct and it should
help to get more test coverage.

- thomas

--
Cheers,
Alberto Ruiz