Qt Documentation Make-Over

One of the better ideas I had this year was to work in July and take vacation in late summer. The northern European countries are essentially shutting down in July, and for me as a program manager that means that I have time to work on a few things that might actually make it into the next Qt release - ideally without introducing new bugs that somebody else has to fix when things are less quiet. Documentation fits the bill perfectly, and with my vacations coming up it was time to merge and push last night.

For Qt 4.6 we wanted to give the documentation a face-lift (Times New Roman is sooo 1990's), and we had started with polishing the style-sheet. Choices of color and font-sizes are of course a matter of taste - and a great topic for long mailinglist discussions - but we threw in some improvements to the layout of the class documentation, and I think the new look is really a great improvement, even if you are fan of serifs ;)

And then there was the content and the content structure, in particular the index page. Feedback we got from users and from new Trolls that tried to find their way through the documentation indicated that it was not easy enough to actually find information. After Qt 4.0, where the index was updated to highlight how Qt 4 has changed and improved compared to Qt 3, we just added more and more links to new modules and frameworks. So things started to become cluttered, and with Qt 4.5 we were simply running out of space on the index page. So for July I hoped to get some cleaning up done, and I wanted to come up with an overall structure that is a bit more use-case oriented, and less about "lists of things".

So as of today, the Qt 4.6 snapshot documentation has a new index and a bit of a new structure. At first glance the index is not that different from the one that worked for 10 years, so I hope Qt veterans don't get a shock :) And the new structure is not a radical departure either, but rather an attempt to better integrate framework and technology documentation with the C++ reference documentation of relevant classes. The integrated search should satisfy those that have used the "list of all something" pages and then searched on the downloaded page. A few things are gone, esp some of the categories in the "grouped classes" page - I hope nobody will miss the lists of "main classes" or "various other useful classes". And that you have to go to the How-To's and Best Practices page to find the Porting from Qt 3 to Qt 4 guide is hopefully ok as well.

There is of course still lots of work to do. Some of the top-level topics are not very well documented, we have for instance no good overview about how to do file I/O, and "Development with Qt" should be more about Qt Creator and less about command line tools. So this has just been "phase 1" and some writing needs to be done, not only about all the cool new stuff that's coming in Qt 4.6.
On the structural side, examples could be better integrated into the text; and on the web, http://qt.nokia.com/doc shouldn't be a list of links to historical Qt, Qtopia, Jambi, QSA and Teambuilder documentation and be replaced by the new index page instead. And finally, we want to include feedback functionality in the online documentation pages, and maybe have a side-bar for navigation (although probably not one of those dynamic trees that require lots of scrolling).

Well, I hope lots of you appreciate at least some of the changes, and have ideas and feedback otherwise! I'm looking forward to finding lots of comments here, and contributions through the open repository when I come back from vacation. And if you really want to get your hands dirty, then come back in a few days and check the open positions for Technical Writers in Berlin, Brisbane and Oslo!