The response on my first blog post about the documentation facelift was so huge that for a moment I was wondering of what I had gotten myself into.:) A response like this would for sure set the level of expectations sky high and be giving our team a lot of work to be able to meet our users’ wishes. Yet again, that is what design is all about – meeting the needs and demands of the people using the product. Moreover, getting a response and engagement like this is more than a designer could ever wish for. It shows that our users care about the documentation, and that is very inspiring.
Now, with this in mind we continued the work by creating a user test that we ran at Qt Developer Days in Munich a few weeks back. If the response on the blog post was huge, the amount of people doing the test was even larger. Close to 15 % of the Developer Days attendees did the survey, and we got lots and lots of good feedback. I want to take this opportunity to thank all those who participated. All together you spent close to twelve hours giving us valuable information for our design process. That is amazing! 
We now have good numbers on which solutions you want, and even better numbers on what you do not want. In addition to the poles, we got many constructive comments, which have been very useful in the process so far. To a large degree, the feedback from the test reflects the results from the feedback on the first blog post. Therefore, without dragging things out further I will tell you about the results from the test.
Design profile
In the test the users were told to choose from a set of different design concepts. The first three concepts were quite similar to the current design, displaying a set of categorized link menus. The design that got the most votes was the one using colors, icons and visual structures like borders and bullet points. This was not really a surprise since the blog feedback gave us the same indications. What did surprise me though, was that you didn’t want search results from the Google custom search engine embedded in the documentation pages. That is a clear indication of the value of user testing.
However, to sum it up, the design and feature profile you want us to use is:
- A front page similar to the current one, only using more colors and some discrete icons for recognition.
- A search box, preferably with automatic suggestions for keywords as you type. Ajax search design example
- A line of bread crumb links in the top area of the page, visualizing the page hierarchy and enabling the user to “jump” to pages several levels up. Bread crumbs design example
- A left-side menu on sub-level pages (like the class pages), ordered in a hierarchical way. Menu design example
- A way to hide and show detailed information. Show/hide design example
- A history box displaying resent searches.
You have also said that you learn best from reading and testing examples and how-tos’. We have a great collection of examples already, but we could also create more of them.
Your list of wishes
As we now draw nearer to Christmas, the concept of wish lists should be familiar to most of us. We send of our list to Santa Claus – or tell our beloved ones what we wish for – and then hope for the best. Sometimes we get what we wish for, and sometimes not. My point is this; the list of wishes will be our guide on the way to what I hope will be a good design, but it will not be a guarantee to make your every wish come true.
Our goal is still to create a design meeting the needs of both the experienced and new Qt users. We need better navigation, better ways to categorize overviews and to improve searches. In other words, we have a lot of work in the months to come. We need to further analyze the design and find out how we best could implement the new solutions. There will be some short-term goals and some long-term goals. I will blog more about them as soon as they are implemented. I still urge you to keep the feedback coming in. It is useful for us and very inspiring.
Possibly related posts:
8 comments
Add the ability for anyone to add comments to functions. This way we can easily point out errors in the documentation. We can also provide new examples, clarifications when the docs could be better, and missing see also’s.
Dear Santa,
I’d like to see a good integration with QtCreator. Maybe the style could even match QtCreator’s one when embedded (buttons, gradients, menus and stuff)!
+1 for the AJAX search box!
I’d also like links in the documentation that directly link to the sourcefile (+line!) on gitorious. This is for several reasons: Sometimes you have to write something that was definitely already written somewhere but you don’t know where, BUT you know that a certain method MUST use it. So you’d like to take a look at the source of this method. (E.g. you want to write a MyGraphicsWidget::mapFromGlobal(const QPoint&) method, QGraphicsWidget::isUnderMouse() just does something like this so taking a look at the source of isUnderMouse() helped me to implement this method.)
I think it shouldn’t be hard to implement some code that inserts links like:
http://qt.gitorious.org/qt/qt/blobs/4.5/src/gui/graphicsview/qgraphicsitem.cpp#line4794
Other documentation systems even provide an AJAXian way to load the source of a method embedded into the documentation!
The number one request I get from people is a way to learn both C++ and Qt at the same time. I don’t know much where to send them to learn C++, pretty much everywhere seems to be full of cruft elegantly replaced by Qt they would have to unlearn.
If you don’t want to introduce people to C++ yourself, it would be appreciated if you could point to a good introduction that would naturally lead to Qt.
@Dan: An Introduction to Design Patterns in C++ with Qt 4
(See http://qt.nokia.com/developer/books/an-introduction-to-design-patterns-in-cpp-with-qt4 might be a good book.)
I haven’t read it, but the cover text is: A complete tutorial and reference that assumes no previous knowledge of C/C++, object-oriented programming, or GUI programming, and can be used as an undergraduate computer science textbook.
Haven’t the also-popular concept 3 from the previous blog post been considered? I hoped it would win, oh snap!
@Benjamin Meyer
Sounds like a good idea to me.
Introduction to Design Patterns in C++ with Qt4 is also open source maybe it must be added to be a link in the books area
http://cartan.cas.suffolk.edu/oopdocbook/opensource/index.html
Comments on this entry are closed.