Last fall I wrote a couple of blog posts about our visions for redesigning the Qt Reference Documentation. We asked the community for feedback on how the documentation could be improved and posted a few suggestions. The response from the community was tremendous. Peppered by feedback and full of inspiration I went to the drawing board and started my work. Right before summer the first “stable” version of the new documentation was published in the 4.7-snapshot, and now we want to get your feedback, before we continue.
New features
The documentation published online has got some new features and a new graphical theme. However, the new design is not all graphics. The most important changes made are the new navigation and usability features. As mentioned, on the left side in the online version you will find a menu providing links to some of the most important pages in the documentation. However, this is not the main feature of the menu. It also sports an AJAX-based search box, which will “automagically” adapt the links populating the menus to match your search. This works much like the index search in Qt Assistant and other traditional help applications.
Basically, it works like this: When you type in, let’s say “QDockWidget”, the content of the API Lookup menu will provide links to the class reference documentation for QDockWidget. The API topic menu will provide links to articles relevant to QDockWidget, and the API Examples menu should provide relevant examples.
We also wanted to improve the usability of the documentation content. At the top of the main page section in the online documentation you will find a toolbar sporting tools like text resizing and printing. This is also where you will find the bread crumb bar providing shortcuts for navigation. Currently, the moment the bread crumb reflects only the hierarchy of the pages and not the browsing history. We will evaluate how this works based on the feedback you provide us.
We have also worked on on-page navigation. You will find that we have replaced the “next/previous page” navigation with a table of contents that lets you navigate directly from the top, down to the content you want to read. This will save you clicks, hopefully reflect the relationship between the page sections, as well as making it easier to print and handle the content.
Structure
One of the most important documentation pages is the index page. Being the entrance to the complete documentation it needs to reflect both the whole documentation content and stay nice and tidy at the same time. That is why one of the most important tasks we are working on these days is creating good overview pages to take you down into the greasy matter. We are keeping overview pages like “All classes” and “All functions”, however renamed, and focusing on high-level concepts to collect different technologies and techniques used with Qt in the remaining overview pages. In addition to the menu search we hope this will make the journey from question to answer quicker.
We also wanted to make the documentation easier to use in combination with other application windows. By resizing the window horizontally, you will find that the style will adapt to the width of the page, hiding/moving sections that takes up space you need for reading. That way you can have both your favorite editor and browser on top of your screen as you are working.
Feedback, please 
We have many ideas for further development of in the months and years to come. Several projects are running to make the Qt documentation a richer and more useful tool. However, we need your feedback on what we have done to make good decisions on our next steps. By clicking the feedback link at the bottom of the main section on every page in the online documentation, you will be able to leave feedback to us.
So, please go over to http://doc.qt.nokia.com/4.7-snapshot/index.html and give us your review.
Note: This feedback should be limited to the documentation of the page you are browsing. Please feel free to submit suggestions and large bugs in our bug tracker system.
Our goal is for you to spend as little time reading documentation, and more time developing good application. This is – so far – our attempt to reach that goal. However, there will be more to come.
On behalf of the Qt Documentation Team
Morten E.
Possibly related posts:
29 comments
Yes the new look is much better. good job
I’ve used both, and I rather like the old style. I think, because its waht I;ve been using for the bast 5 years. Or maybe its because of rendering quirks that have yet to be fixed. (I’ve reported some)
I tried the search and here’ my notes:
I entered “Qabstract” in the search box.
It gave me:
* Found 32 hits
* Class index
* Function index
* Modules
* Namespaces
* Global stuff
* QML elements
* QAbstractAnimation Class Reference
* QAbstractButton Class Reference
* QAbstractEventDispatcher Class Reference
* QAbstractExtensionFactory Class Reference
* QAbstractExtensionManager Class Reference
* QAbstractFileEngine Class Reference
* QAbstractFileEngineHandler Class Reference
* QAbstractFileEngineIterator Class Reference
* QAbstractFontEngine Class Reference
* QAbstractFormBuilder Class Reference
* QAbstractGraphicsShapeItem Class Reference
* QAbstractItemDelegate Class Reference
* QAbstractItemModel Class Reference
* QAbstractItemView Class Reference
* QAbstractListModel Class Reference
* QAbstractMessageHandler Class Reference
* QAbstractNetworkCache Class Reference
* QAbstractPrintDialog Class Reference
* QAbstractProxyModel Class Reference
* QAbstractScrollArea Class Reference
* QAbstractSlider Class Reference
* QAbstractSocket Class Reference
* QAbstractSpinBox Class Reference
* QAbstractState Class Reference
* QAbstractTableModel Class Reference
* QAbstractTextDocumentLayout Class Reference
* QAbstractTransition Class Reference
* QAbstractUriResolver Class Reference
* QAbstractVideoBuffer Class Reference
* QAbstractVideoSurface Class Reference
* QAbstractXmlNodeModel Class Reference
* QAbstractXmlReceiver Class Reference
What I expected to see was:
* Found 32 hits
* Class index
** QAbstractAnimation Class Reference
** QAbstractButton Class Reference
** QAbstractEventDispatcher Class Reference
** QAbstractExtensionFactory Class Reference
** QAbstractExtensionManager Class Reference
** QAbstractFileEngine Class Reference
** QAbstractFileEngineHandler Class Reference
** QAbstractFileEngineIterator Class Reference
** QAbstractFontEngine Class Reference
** QAbstractFormBuilder Class Reference
** QAbstractGraphicsShapeItem Class Reference
** QAbstractItemDelegate Class Reference
** QAbstractItemModel Class Reference
** QAbstractItemView Class Reference
** QAbstractListModel Class Reference
** QAbstractMessageHandler Class Reference
** QAbstractNetworkCache Class Reference
** QAbstractPrintDialog Class Reference
** QAbstractProxyModel Class Reference
** QAbstractScrollArea Class Reference
** QAbstractSlider Class Reference
** QAbstractSocket Class Reference
** QAbstractSpinBox Class Reference
** QAbstractState Class Reference
** QAbstractTableModel Class Reference
** QAbstractTextDocumentLayout Class Reference
** QAbstractTransition Class Reference
** QAbstractUriResolver Class Reference
** QAbstractVideoBuffer Class Reference
** QAbstractVideoSurface Class Reference
** QAbstractXmlNodeModel Class Reference
** QAbstractXmlReceiver Class Reference
* Function index
* Modules
* Namespaces
* Global stuff
* QML elements
The index page is indeed a major improvement ! Only thing I noticed: The AJAX-based search is pretty picky. E.g. searching for ‘Designer’ turns up ‘No results’: You have to type ‘Qt Designer’. But even this won’t show up ‘A Quick Start to Qt Designer’, which is the first hit in the index of Assistant.
Yes, I like it very much!
I have never seen such a documentation. The best ever!
I develop every day software using Qt and Qt creator is very nice. When i need to lookup something, i just hit F1 and i get it! It is soo fast, i spend no time searching something, it’s just there!
Love it!
Nice job !
my small own experience : I very often use the “List of All Members for ” when I look for class information. Could it be possible to see at first sight the nature (function, property, signal,slot …) of the listed members and the origin of the member in the object inheritence tree. Perhaps it could be done by using typos or colors for nature and tooltip for origin.
When I typed in qmake into the search, the first thing I saw right under the API section was no results, being new to this interface I thought it could not find any results for qmake. After a few more times I noticed it was giving results in the Qt topics area. It might be helpful for novice users to break out the search area as it now appears part of the API frame so your eye is drawn to that area and not the whole left side. Aside from that first impressions are very favorable.
This version of the documentation is much worse than the previous one. Navigation considerably complicated.
Take the tutorial “Address Book” (http://doc.qt.nokia.com/4.7-snapshot/tutorials-addressbook-part2.html). Unable to walk back and forth.
Now I see the furbish gloss, which is more important in selling cell phones for housewives than for programmers.
In versions
Online search is really useless… When searching for QWidget in Assistant it shows every class that inherits QWidget but not QWidget itself. Besides, Google searches better in any case (due to all browsers have search line, duplicating search in page itself not a good idea)
Looks nice!
I agree with the comment above on the “list all members for” page. It would be nice to have all of the information about each member right there–public/protected/etc. signal/slot/etc. static/instance.
Also, if each page could have a “latest” link that takes you to the latest version, that would be helpful. Right now, for example, Google often returns a version 3.3 or 4.3 page as its top hit. I can go up to the address bar and change the version to “latest,” but it would be nice to have this automatic. Implementing it now would “future-proof” the pages; even better would be if past pages could be retrofitted with this feature.
Keep up the great work!
Looks nice and practical, congrats!
My only suggestion is to spend some time reviewing the structure and do some SEO (Search Engine Optimization) on the whole doc site. My major problem with online qt documentation right now is that google never returns the results I want because of the mix of multiple versions of every documentation page.
So please make sure your documentation site is google-friendly.
You have an error in http://doc.qt.nokia.com/4.7-snapshot/best-practices.html with one of the headings showing an “&” instead of “&”.
Search results for classes should show at the top of the “API Lookup” box or somewhere else easily accessible or with better visual separation. Currently the results are hard to see as they look exactly like the menu items which have been there all the time.
Great ! Looks very nice
Too bad that praticly all classes pages (except index) do not respect the DOCTYPE they have in source file…
Looks definitely cleaner than before. But the issues above should be considered, searching has not been improved at all.
Also i don’t like those tables, in larger Lists it would be helpful to have horizontal lines.
Thanks for all the comments!
Please keep them coming. This feedback is very important to us.
Now, here are a few comments from my side.
First of all, a comment related to the search feature. The current format is not working very well and will be changed. This is already in our plans, and will probably be implemented within a few weeks. The search engine is currently using a test index which is in need of updating. Once this is in place we should be able to provide a proper keyword look-up. Now the other thing we would like to do is to keep the menus free from search results, and display the results in a block of its own, hovering on top of the page until it is out of focus. This should provide a more usable interface for navigation.
@lit-uriy: Not all the issues regarding navigation have been solved yet. The back and forward links are coming back in, and their absence is due to a bug.
@xgouland and @dave: Regarding the “List all members” page – we will have a look at this and see how we better can reflect this in the docs.
@dave and @Ademar
Regarding the latest link – this is available by clicking on all versions and continuing to snapshots. Now we have changed the server settings so the search results returned by Google should improve, but it takes some time for the search engines to pick this up.
Well i am a big docu user.
And after the first tests i did the new documentation is really a large step forward.
It looks nicer and althoug it is “only look” it makes it better because it feels not clumsy and old. It is just more sexy. I like that.
I like also table of context and the new index site.
but yes the search field is not so potent like the qt assistant version.
And to tell the truth THAT is a big minus.
Because in fact you use a docu once for learning. Here you use documentation with links and so on.
This part is perfect.
You use docu for quick reference, for something you remember that was kind of …
and here is the most important thing a good and powerfull search.
Here … it seems missing.
What i would like to see would be a more “Thunderbird” like search.
Not only enter a text but also a way to encircle the little bastard with additional options until you found out what you searched for
I must say I have always been impressed by the index quality in previous versions. Complete and easy/quick access. I use it often tens of times a day, for years. In that domain, what I see in http://doc.qt.nokia.com/4.7-snapshot/index.html
is way under
Someone pointed something symbolic: just type “QWidget”. In that case, what one expects is a 1 click access to the class description. Not with this preview.
All the rest seems better
Where are the overviews??
For example, I frequently go to the “Making Applications Scriptable” page. I simply couldn’t find it in the new docs.
Since I remembered the name, I typed it in there, but the search results are way non-intuitive and unusable. I mean, I was staring for a few minutes at that “Found 1 hits” label, thinking – so where are these hits exactly? Until I noticed the completely “non-search-result-looking” yet another link there.
So I click it, which sends me to “http://doc.qt.nokia.com/4.7-snapshot/scripting.html”. And here, there is no indication where I am (in the global document tree structure). There’s no option to go up, next, prev, nothing! It’s as if it’s a completely standalone root-level page with no one linking to it.
This is a serious downgrade.
It sure is pretty, and you can get more documentation on the screen at once, and zipping down to say the signals of a class is far easier, and I find it more intuitive to figure out what module a class is in, but the search is horrible for all the reasons mentioned already. In fact I tried typing stuff like “QLabel” and then clicking the “class index” at the top assuming that would take me to the QLabel page? It did not, it actually took me a few minutes to notice the QLabel class reference at hte bottom of that list. So searching must be improved dramatically, right now it’s worse that what you have currently since it’s counterintuitive. I disagree with others about the graphics, I think they really add a lot and make the docs more usable.
I am not seeing the new page layout at the link mention in the post. It’s like missing stylesheet:
http://i.imgur.com/EETRl.png
The shot was taken in FF 4 beta but it’s the same in IE8 and FF3.6.
Hm, I only see the search box and other menu items for a fraction of a second and then they are gone. Strange. I use Firefox 3.6.8 on Fedora 12 x86_64 from the remi Repository.
If you can say, what syntax and tools to do you use to create the documentation?
The one thing that annoys me most is the sorting of the class index. When I scan for a particular class (I might not remember its name completely so I like to look at the list) it is much more natural to scan columnwise (downward) instead of one row at a time. Trying to scan alphabetically in the current layout really makes my head dizzy…
When that is said, I really love how the page handles a really narrow window size, as putting the class index in a sidebar in firefox is just brilliant (and then the list of classes is one column wide, yay).
Btw, I understand the reason (simple CSS for dynamic width support) for sorting it the current way, I just don’t approve =)
At least couple days ago, I saw some page consistently using & for ampersand, instead of correct & – I guess that’d be documentation generator bug.
Also, on some random page, I observed Qbject (that’s not O, but Q, and it should have been QObject).
Just writing it down here before I entirely forget. Maybe someone takes a look.
Thanks Guys for making the Qt docs so beautiful.
It is very much fun to read through the new theme.
Keep it up guys. Get ready to challenge MSDN..
No Chinese version?
The online documentation is very good. Here good job. But the assistant… pure disaster. No fun working with that anymore. The old styles worked far better.
Can this style glitch in the upper edge be removed?
http://i233.photobucket.com/albums/ee112/tanuki64/NewAssStyle.png
Hmm, I find the new version slightly less readable than the old – it’s slightly harder to scan visually.
Example: look at the subsections of http://doc.qt.nokia.com/4.7-snapshot/qwidget.html#details and note that the section breaks are indicated only by a very slightly larger text and very slightly larger vertical spacing. More emphasis on the section breakdown – say, bolding the section titles or giving a horizontal rule to define them – would be beneficial.
In the same thread, I’d also recommend a slightly darker background color in the blocks – they again denote the separation of logical blocks (in this case, particular functions) and attract the eye to the important piece of text to find when scanning the page.
Having higher contrast between different logical blocks would improve usability.
After writing this, I looked to see how Apple did it, since they usually get design and usability fairly right: http://developer.apple.com/mac/library/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_6.html
Comparatively, they use more vspace to indicate subsections, and bold their sections. Code snippets and tables get a light (but still more pronounced) background. This is closer to what the Qt docs did in previous versions, and closer to what I had in mind for the future of documentation.
Thanks!
Comments on this entry are closed.