GUI Toolkits and the art of Documentation

For an API designed to empower you with the ability to create graphical interfaces for your applications, the documentation for wxWidgets is really lacking when it comes to graphical aids.

For the most part, the reference documentation for wxWidgets is complete, only the newer/lesser used/incomplete features lack documentation. It's also got pretty good descriptions on how you're meant to use certain classes.

However, it seems straightforward to me, that when creating something visual from pre-defined building blocks, it would be helpful to have an example of what those building blocks might look like. For instance, take a look at the following items:

• wxNotebook
• wxToolbook
• wxTreebook

When reading the documentation, it's not hard to figure out what a "notebook" probably is (though of course, until you actually use it, or see it in action it's not for definite). A "toolbook" though? Not sure what that is, apparently it uses a toolbar instead of tabs. How does that work? Thankfully there's a sample in the SDK which demos all of the various "book" widgets. At which point it becomes obvious what a "toolbook" is and you start kicking yourself for not realising from the off. Though you wouldn't have had this confusion in the first place if the documentation had some pictures or diagrams to show you exactly what it is.

Though in that instance we were able to rely on the presence of a sample to inform us that's not necessarily always the case. But in either case, it would be nice not to have to compile some source code in order to know what a certain widget looks like.

It's not as though this problem is limited to wxWidgets either. Here's the official MSDN documentation for a couple of widgets:

• CListBox
• CListCtrl

They've gone to great lengths to describe how these two similarly named but very different widgets look and operate and yet there is not one image to assist the description. A picture is worth a thousand words became a cliché for good reason, don't forget. Juce also does exactly the same thing. Perhaps it's unfair to judge their documentation when a lot of it is actually generated from the source code - but there's no reason why they couldn't have a separate page with a bunch of reference screenshots (which they could then link to from the main docs).

Is it just me that finds this to be an incredibly obvious oversight?