Writing good documentation is not all about the quality of what we write, but also about how we present the information. A large base of knowledge is of no use to you if there is not a good way of accessing the information you are looking for. The documentation must be accessible and easy to use, as well as accurate and informative.
Design philosophy
Lately, we have been looking for better ways to present the Qt documentation on the web. Our current documentation consists of static pages linked together in the good old fashion way of Web 1.0. Yes it works, but the potential of Web 2.0 is worth investigating and could increase the usability of the site. Ever since Qt version 2.3 (at least), the Qt documentation have had a uniform look and structure. During the time since those days, Qt has evolved, gained a lot of new features, and now covers a lot of more ground than its predecessors. This evolution has also effected the documentation, making the base of information larger and more complex. Despite the growing amount of information the documentation has kept its simple but effective design because it works for our users. That is something we need to preserve when adding new features to it.
If you have peaked at the documentation in the Qt 4.6 snapshot, you have probably noticed the search box added in the top corner of the index page. This is a custom Google search engine, scanning our documentation for results matching your query. Now, there is nothing revolutionary about this feature, but this is one way we can improve the documentation usability. Adding such a feature has no remarkable impact on the rest of the documentation. However, adding new features to the site should not be done without research. If we are going to do changes we need an idea or a philosophy on what we want to accomplish.
We want the documentation to be as user friendly as possible. That means that it should be easy to find detailed information on a subject if you are an expert and knows what you are looking for. The same should apply if you are a beginner looking for good tutorials and overviews. We also want to provide a structure that requires a minimum of searches and mouse clicks. Today, a search for detailed information on a subject can require browsing as much as seven or eight levels down using links from the index page. This makes navigation hard and tiresome, if it is not combined with queries to a search engine. Dynamic menus and a flat structure could help us on our way accomplish this. By creating a good cognitive design, we want to make your journey from question to answer as short as possible so you can focus on creating good applications.
So with these goals in mind we are trying to find a structure and a set of new features that will improve the future Qt documentation. Finding such a structure requires recognizing how the different elements in the documentation relate to one another. Questions like how they should be categorized regarding technologies, types of features or platforms, comes to mind and needs to be sorted out. Also we need to sort out which categories are more relevant and needs to appear at the front line to keep the structure flat. To keep a flat structure, the real trick will be to find out how to present as much information as possible on the least amount of space, and without making it chaotic.
Design reserach
That said, there are probably as many opinions about how the documentation should be organized as there are Qt users, and it is exactly these opinions that we are interested in. That is also why we will talk to our users about this issue during Devdays in Munich this year. We want to do some research on how developers use the Qt documentation, and how they would like the documentation to evolve.
As part of our research, we have created a set of different sample pages, showing a range of concepts from the super-social-inspired pages, to minimalistic and clean overviews. Our goal is to visualize different concepts and get feedback on what our users think of them. This user test will mainly take place face to face with developers during Devdays in Munich. The results of this user test will be brought back to the team in Oslo and used as input for the design process.
With a few weeks left until Devdays, we would like to show you a few of the features included in these sketches and say a few words about them. This will enable you as a user to give us your opinion even if you are not going to Devdays, and it is giving us a chance to adapt our approach to the problem. However, I must underline that these samples only show the wide specter of choices we have when looking for new features. Our purpose with this preview is to get feedback from our blog readers regarding what they like and don’t like about the features. In the list below you can have a look at our ideas, and add your comments.
Different concepts
Suggestion 1.
This is the current design, displaying menus of links in different categories. The number of links has been set to a minimum, but still covering the essential parts of the documentation.
Suggestion 2.
This sample uses icons and colors with the link lists, adding cognitive effects to the design. It also makes the page more pleasant to look at. It contains a search box for queries in addition to a line of top-level links at the page top.
Suggestion 3.
This sample is stripped of all eye-candy and cognitive image use. This makes the listed links more visible as long as they are categorized logically and the number of links is limited. The page contains a line of top-level links and search box at the top of the page.
Suggestion 4.
This sample shows a very minimalistic page containing only a few links and large images. This limits the navigation from the index page, but makes it easier to locate the relevant category to browse through. This page also contains a line of top-level links and search box at the top of the page.
Suggestion 5.
This sample has a more “social” concept. In addition to a menu with a hierarchical structure to the left, it has three menus showing content based on what the user previously has browsed in the docs, as well as menus based on ranks and top searches. As before the page contains a line of top-level links and search box at the top of the page.
Suggestion 6.
This sample is based on a “social” concept. These elements include menus containing top searches, history, blog entries etc. This can be an effective way of notifying the user about new features and popular subjects.
Search features
Suggestion 1 - Search features
This sample is based on the current design, but also provides a search box using AJAX requests to create a list of suggestions when typing.
Suggestion 2 - Search features
This sample demonstrates how Google search results can be integrated onto the documentation page. The user avoids leaving the doc pages and can navigate the docs without having to go back from the Google result page. Please note the keywords on the right hand side making it easier to further narrow down the search.
Navigation features
Suggestion - Navigation features
This sample is based on the concept in “Suggestion 5″, displaying a long page, containing menus and the search box. In addition the header of the page is floating, so the links and search box will always be visible. Also note that the bread crumb-links display a drop down menu to other relevant documents on the same level. Finally, the descriptions of functions etc., is hidden in a collapsible paragraph to make the content less chaotic.
Feedback
We want to create a good and usable design for the documentation. That is why we want your feedback, and there are two ways to contribute. You can add your comments to this blog entry. However, if you are going to Devdays in Munich, please stop by us and participate in the user-testing. It won’t take long, I promise. 
You may also add your own ideas in your comment. It just might happen that you thought of something we didn’t, which could be the next genius idea for online documentation.
