Andre added the first real doc notes.
The Qt Documentation - Notably New Features
We were not joking when we announced on April 1st that Qt documentation would move in with us here on DevNet. People have been praising the extraordinary quality of our documentation for decades – precisely why we’re not even thinking of touching it. However, even great things can be improved with a bit of modern wizardry, and we saw potential for adding some neat Web 2.0 features.
It’s time to present our Qt documentation integration efforts! [developer.qt.nokia.com]
The official Qt documentation, including all previous versions, is still on http://doc.qt.nokia.com/ and will be for many months to come.
The new, enhanced edition of the Qt 4.7 documentation hosted on the Qt Developer Network has a slew of additional features to help make developers’ lives easier, and possibly more rewarding.
Without further ado, here is the rundown:
Each page in the Qt 4.7 documentation can now be commented (aka “doc notes”) – by anyone.
How often did you find yourself thinking: “There must be someone out there that has solved this tricky bit before?” You bet there is! Thousands of very clever developers out there are using Qt, and you fine folks generate tips and tricks at a phenomenal rate.
Imagine how a year from now each Qt class/example/demo will have a thick selection of high-quality crowd sourced gems of wisdom attached to it. Wouldn’t that be all sorts of awesome?
We have thought long and hard about the quality issues you often see in freeform commenting. So we came up with three things to address this.
One is the -5 / +5 rating system, mildly similar to other places on the internet you may know. Notes with a negative rating are hidden by default; new notes start out with a rating of 0.
Another one is a rank requirement that can be set for access to adding doc notes. That would prevent anyone from registering and immediately posting a doc note with a link to their favorite scam site. Currently it’s open for everyone; we’re ready to adjust if needed.
And then there is the moderation queue. If a doc note is set to “buggy”, “inappropriate” or “outdated” (available in the rate down widget) it is hidden and put in a queue for review by those interested in helping us to keep things tidy. After getting revised the note is shown again on the documentation page where it came from. A negatively rated doc note will be reset to 0 after revision. A full diff is available per note.
Notes can also span several versions. A particularly good note on QSqlDriver might be visible on Qt 4.6 through to future Qt 5.0 pages given that its content still applies.
We chose three categories for doc notes: “Informative”, “Best Practice” and “Cool Hack”. While writing a doc note you can indicate what category you think that note belongs to, or you can do so when rating. A simple majority decides.
All notes are shared under a creative commons license. Here’s an example page [developer.qt.nokia.com]
Once you set a docmark it shows in the sidebar and control panel.
If you’re anything like us, you tend to look at the same documentation over and over again while your working on a certain problem. Now you’re able to “docmark” those classes directly on the page and reach them from within the sidebar, regardless of where you are on the Qt Developer Network. You can also remove them by clicking on the little [x] in the sidebar or, alternatively, from your profile control panel.
In a next step we will give you the possibility to make all your “docmarks” publicly visible on your profile if you wish to do so.
Tagging and Rating
Using tags is an easy way to find related content.
It wouldn’t be our style of integration if there were no tags and ratings involved, would it? Every documentation page that is displayed within the Qt Developer Network can be tagged and rated to smoothly blend in with all other content types on the site. That also means that class documentation will show up as “related content” everywhere else (coming soon™).
We’re working on an auto-tagging feature which ads class and module tags to all documentation. It will replace all duplicate user generated tags of the same content; no need to dig out your scripting skills for easy points.
If you want a purer version of the Qt Documentation, you can enable what we call the “simple mode”. It will make the tagging and rating box as well as the Doc Notes at the bottom of the page disappear and only keep the doc navigation and your personal sidebar. We have plans to make this mode even more focused.
Currently, but not for long, the Simple Mode is only available if you’re logged in. Your preference is stored as a cookie.
Alternative names: focus mode, cave man mode, speed mode, use the force Luke mode, dialup mode, kamikaze mode, Klingon mode, vanilla ice cream mode etc. Pick your favorite.
Auto-complete for all Qt classes
The updated Qt documentation has its own search, just like the wiki. All the Qt classes are available as auto-suggest that takes you there in one click. For other search phrases we use a familiar Google custom search engine.
Of course, documentation will also show up in the site-wide search in its own tab. You will find all relevant content in one place when you’re searching for anything specific. We think that’s pretty handy.
Points and Badges
You were waiting for it, weren’t you? Naturally, all actions you take regarding the Qt documentation (other than reading it) will be treated as welcome contributions and will give you points. We updated the Points and Ranks page; take a look if you want to know what will push you up the ranks the quickest.
We also have some new badges in the works that will show up on your profile soon if you’re being busy on the documentation pages.
How to give feedback
We’re active in the Beta Tester forum and on the JIRA bug tracker. Our main focus now is to harden the features already out there (19 open issues currently) but we’re always looking for the next useful feature to work on.
Who did it?
The roots for this project came from the Qt Doc teams DITA project that will be blogged about on Labs. Using this XML format we, the Qt Web Team, were able to handle the 4k+ pages of the Qt Doc in a sane manner.
Since the Qt Web team is lightly staffed we hooked up with our partners in crime, the web developers at Trollweb Solutions [trollweb.no], to get it done on time. They rock in general, a special shout out to Bjørn Børresen [twitter.com] for excellent effort. Before you ask, they have no relations to good old Trolltech, we just have a thing for trolls here in Norway!