wxPython and wxWidgets Documentation Gripes

wxPython is an interesting package, built on the underlying wxWidgets C++ GUI library. It’s full-featured and relatively platform independent. However, it suffers from a malady common to a lot of open source software.

The documentation sucks. Period.

What little there is consists of a set of dumbed-down Epydoc HTML pages. Other than that the user is referred to the original wxWidgets documentation, which is only slightly better. If a developer needs detailed information then it’s off to the source code to see how things are done, or perhaps a book like “wxPython In Action” might help. Or, if one is really desperate, “Cross-Platform GUI Programming with WxWidgets”.

Now, I have a problem with code that forces me to read the source to see how it works. I don’t have time for that. I’m busy, I need answers now, and I really don’t care how clever someone thought they were when they wrote the code. I expect a library module to be like a box of IC’s or a selection of nuts and bolts; I look through an index, I find what I think I need, I read a description of what it does, and if it looks good then I use it. Just as an aside, if people would do this then it’s virtually guaranteed that re-use would go up and time wasted reinventing the wheel would go down.

The classic example of how to do this correctly is the standard set of man pages supplied with Unix systems. The man pages for things like open() and close() are clear, concise and accurate. The X window system also ships with a comprehensive set of man pages, and there are numerous detailed books available that provide well-organized definitions and examples (like the complete X programming library in something like 6 volumes or so). There is no need to look at the source code to unravel how something is supposed to work and how to use it.

I also have issues with the book “wxPython In Action”. A reference work it is not. It is, at best, a cookbook. Some of the descriptions are detailed, but many are just top-of-the-waves views of GUI functionality. Throughout the book there is the underlying assumption that the reader will need to refer to the original wxWidgets reference materials to get the essential details. For people without extensive C++ experience this could be very frustrating.

Although I might lament the loss of printed documentation (reading stuff from a screen gives me a headache) I also know that printed manuals and reference work won’t be coming back into vogue any time soon. But more than that, I also lament the time when documentation was considered an essential part of a professional software product. By way of contrast, consider the documentation that Microsoft ships with its Visual Studio products. It’s comprehensive (albeit in an electronic form), well indexed and relatively readable. I can’t honestly apply these descriptors to either wxPython or wxWidgets.

The sad part is that I really wish I could.

0 Responses to “wxPython and wxWidgets Documentation Gripes”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow Crankycode on WordPress.com

Little Buddy

An awesome little friend

Jordi the Sheltie passed away in 2008 at the ripe old age of 14. He was the most awesome dog I've ever known.


%d bloggers like this: