.webp)
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.
