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 <pho...@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
_______________________________________________ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list
