RSS Feed

I miss Qt (or what cute documentation looks like)

Posted on Wednesday, July 25, 2012 in Coding

Anyone who has worked with Qt over the years knows that it is for the most part a superset of C++. Qt makes C++ cute (pun intended), it has lots of core (non-GUI) and convenience classes and it has QString. Yes, QString, the class which has implemented almost every string operation under the sun. These days, I mostly do stuff in Java, but I yearn for opportunities to jump back into Qt.

When I started using the Qt toolkit (some 2-3 years ago), one thing that immediately struck me was the intuitiveness of the class and method names. The guys at Trolltech (then Nokia, and now the community) clearly spent quite some time thinking about how to name their classes and methods, and it worked beautifully. 9 times out of 10, when you guessed the name of a class or a method, it was correct. If it wasn’t, a quick internet search revealed the (very similar) correct name. This greatly improves productivity with any library. This brings me to the next thing I love about the Qt….

The documentation. Qt was, at least for me, a revelation in library documentation. For every class in Qt, there was a short introduction to the class with best practices and recommendations, as well as a code snippet (or two) demonstrating the most common use-cases for the class. The code snippet makes use of other Qt classes which work will with the current one and promotes best practices. Most of the time, when you search for a class or method in a library, all you need is the most common use-case and it is tremendously helpful when you can immediately see an example. It’s like a mini-tutorial in every class documentation.

document_all_the_things

This is unlike the Java documentation which I find to be usually very dry and usually in the form of “this class represents blah” or “this class does blah and does it like this” and then some other information. Nothing about how to use the class and no code snippets (or very few if any at all). Normally after finding Java class documentation, you need to Google half the web to find out how to use it.

Ok, I know I’m exaggerating, but go ahead, take a look at the Java File and the QFile class documentations. Then pick any other class you can think of and try again. Which one do you think you will easily get up to speed with? Java docs tell me about the class, but nothing about how I can use it right now!

Now don’t get me wrong, technical writing is hard. I’m not trying to knock on the Java documentation writers, as I am guilty myself. As a developer, there are many things going on in your head when coding and being able to write them down in a way that someone who isn’t in your head can understand is no easy feat. It is just very refreshing to see well-done high caliber documentation and I want to praise them for it. It definitely made my life easier.

I wish all library documentation was as good as Qt’s. Until then, we can all strive a bit more to be better writers.

Share and Enjoy:
  • Twitter
  • Google Bookmarks
  • Digg
  • del.icio.us
  • Facebook

Bring on the comments

  1. J says:

    Having good guidelines for a user interface is very valuable. Having guidelines for good documentation and good API is very valuable. A good help, which the Qt trolls uses, is “The Little Manual of API Design” that Jasmin Blanchette published in 2008:
    http://www4.in.tum.de/~blanchet/api-design.pdf

  2. James says:

    Indeed, the Qt documentation is top notch. Jasmin Blanchette deserves huge credit for the great quality in the docs (he was the main doc guy along with David boddie).

  3. Avi Hayun says:

    I DO blame Java for poor documentation.

    Here, take a look at Microsoft File class documentation:
    http://msdn.microsoft.com/en-us/library/system.io.file.aspx

    Java is not a small startup company which excuses itself for poor documentation because it’s core developers are eating pizzas at a garage and developing new core functionality each other day so they don’t have time for documentation.

    Java is housed under Sun, under Oracle, they could pay for several developers which would sit and upgrade tremendously the documentation.

    I love Java, but their docs suck.

    Avi.

  4. eric-yorba says:

    You’re comparing apples and oranges here; Java separates out the tutorials/examples from the docs, whereas Qt combines both.

    For a Java File tutorial, this is a good place to start:
    http://docs.oracle.com/javase/tutorial/essential/io/file.html

    Both Java and Qt have one thing in common — their docs are orders of magnitude more complete than Gnome’s!

    • Ngewi Fet says:

      Qt has tutorials too. Which go in-depth into separate topics. But it also has code snippets in the class documentation. This goes a long way when you just want to know how to quickly use a class and don’t need all the specifics of how, for example, file buffering works. This is one main reason why anyone can pick up Qt very fast.

      What you say just confirms what I said about having to “Google half the web” to find out how to use a Java class. Look at the link you provide, how much do you need to read before you know how to actually read files. There is a point to be made for succintness of Qt docs.

Leave a Reply to Ngewi Fet

Click here to cancel reply.