PyGTK Documentation Rant

So, continuing on my series about PyGTK, today I'm going to be discussing one of those issues which every new users of some tool or toolset comes across (hopefully, if it even exists): documentation.

Fortunately, in this case, they DO have some documentation. Heck, they've got some tutorials and a reference manual. On the surface it's all well and good, until you start running into a few things which start to become gradually more annoying as time goes by.

1) Inconsistent ordering of method defines
There doesn't seem to be any logic to the way in which available methods are listed out. In particular, it is neither listed alphabetically, nor grouped into categories and listed in some form of order that way. Instead, as deducted from personal experience of seeing other people's code, the order is likely the very order that the items are defined in the code!

While this sort of thing is fine for code, it just doesn't cut it for documentation, especially for reference documentation. Reference docs are meant for one purpose: allowing the user to quickly find technical details about whatever they are interested in.

2) Missing "subclasses" information
Quite often, you may stumble across some entity which looks like it does what it is you want, only to discover that in fact it is just an abstract base class. However, although the docs for this tell you about its ancestors, there is no mention of the things which may be subclasses of it, such that you can go and start probing around those to see if any fit your use cases.

Instead, you must traverse the list slowly, observing whether anything has a name that sounds like it might be that ABC's concrete implementation.

I've had to do this a few times today, and it's really starting to tick me off.

3) Outdated tutorial
Now, this is something we in the Blender community are guilty of all the time, but having outdated tutorials can be a bit of a problem for new users. Especially when the methods shown in the tutorial are actually all "deprecated" methods, with the reference manual actually not showing that these are deprecated in any easily visible manner either.