The Qt Documentation - Notably New Features

by Alexandra in Qt DevNet News (11781 views)

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:

Documentation notes

Andre added the first real doc notes.

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]

Docmarks

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.

Simple Mode

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.

Search

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!

Enjoy!

Picture of Stavros Filippidis

June 15, 2011

Stavros Filippidis, Lab Rat

Nice done! A needed and most welcome feature is now implemented!

Picture of Edorian

June 15, 2011

Edorian, Lab Rat

The new docs look indeed very nice!

Picture of lexfridman

June 15, 2011

lexfridman, Lab Rat

Wow, this is very exciting news. Qt has the best documentation of any software library I’m aware of, but I always loved how a site like php.net allowed comments on documentation, which created large repositories of example code, and useful special case discussions.

Picture of paulo

June 15, 2011

paulo, Ant Farmer

I love it!!

Picture of mlong

June 15, 2011

mlong, Robot Herder

Very nice work indeed! Congratulations to all who made it possible!

Are any future plans to incorporate the Qt Mobility documentation as well? I’d love to see the Docmarks functionality available there too.

Picture of zester

June 15, 2011

zester, Lab Rat

One of the things I admire most about Qt is the documentation, great job. :)

Picture of Fazer

June 15, 2011

Fazer, Lab Rat

Great, but how do you access the new documentation from other places in the DevNet? All links still point to the old docs. Hopefully it’s because you just didn’t have time to change them yet.

Picture of mariusg

June 15, 2011

mariusg, Ant Farmer

@Fazer: The new doc features are released today for testing and general feedback. It will take a while (counted in months) before we do a redirect from the static doc.qt.nokia.com for the Qt 4.7 documentation.

The Qt documentation is a tool in daily use by so very very many. We simply want to make sure everyone is on board with this change and that we annoy as few as humanly possible (hello “simple mode”).

@All: Thanks for the great feedback, we have a good collection of feature requests and bugs to work on to make it even better, stay tuned. And feel free to add more in the beta tester forum :)

Picture of kidproquo

June 16, 2011

kidproquo, Lab Rat

I’ve had a quick look around and things are looking good. However, I have spotted a few issues. Where is the best place to report these?

For example: on this page [developer.qt.nokia.com] there are a few broken links to images.

Also on that page (and all the others I’ve seen), in the code boxes the links to “qml-rectangle.html” seem to break once some styling is done to them so they work when the page is first loaded, then they change to printing the raw html.

Picture of mariusg

June 16, 2011

mariusg, Ant Farmer

@kidproquo: Thanks, we shall fix! The beta tester forum [developer.qt.nokia.com] is a good place to log issues and suggestions. (not this one though, got that logged)

Picture of leon.anavi

June 16, 2011

leon.anavi, Area 51 Engineer

The good documentation is a postulate for success of framework and/or programming language! :) Well done, I like the new look and feel and I believe it will provide better usability for all of us!

Picture of Flux

June 17, 2011

Flux, Lab Rat

It was told two months ago that doc integration in the developer network would work by end of June. Now this is just reality. THAT’S SO COOL!

Feature request: Allow referencing methods with a hash mark: ClassName.html#member. For me it is very useful to point directly to a certain piece of information. I’m using it all the time on the forum.

I see I can do /qml-pathview.html#id-aceedace-e59c-4ab2-ad28-1042fe60d408, but that is not very intuitive.

Picture of mikhas

June 19, 2011

mikhas, Lab Rat
Picture of Volker

June 19, 2011

Volker, Ant Farmer

@unclewerner:

The hash mark linking to methods is already on the wishlist – it will work even more convenient with the now documentation link feature of the forums and the wiki.

Picture of Volker

June 19, 2011

Volker, Ant Farmer

Sorry for double posting, I can’t edit the previous comment or delete and merge it with this one – that only works in the forums.

@mikhas:
the alignment is on the function/method name, so that you can scan those easily. If it were all left aligned, the function names would seesaw permanently.

Picture of bobby

June 23, 2011

bobby, Lab Rat

Awesome idea. Comments will be a great addition for best practices!

Picture of Exodus

July 5, 2011

Exodus, Lab Rat

Excelent! Qt documentation keeps getting better and better. Kudos.

Picture of hamishwillee

July 8, 2011

hamishwillee, Lab Rat

I wish we had the ability to add notes to reference documentation on Nokia Developer. Symbian Ltd had it for a while in the later days. Kudos for listening to developers.

Picture of changsheng230

July 10, 2011

changsheng230, Lab Rat

Better bring Qt mobility doc here ASAP, the mobility doc need to be improved a lot.

Picture of Rahul Das

July 25, 2011

Rahul Das, Robot Herder

Good Idea:) , Motivating..

Picture of skypjack

August 2, 2011

skypjack, Lab Rat

WoW. :-)

Picture of chfox

August 10, 2011

chfox, Lab Rat

very nice

Picture of Castalia

August 11, 2011

Castalia, Lab Rat

Is it true that “each page in the Qt 4.7 documentation can now be commented”? I have a note to add to the QImage class documentation page ( http://developer.qt.nokia.com/doc/qt-4.7/qimage.html ), but though there is a Comments section I can find no way to add a note. I’ve checked several other class documentation pages and found the same situation. And, yes, I was logged in.

Picture of mariusg

August 12, 2011

mariusg, Ant Farmer

@Castalia: It requires the rank of Ant Farmer to add a doc note, this is to prevent the spammers for getting to it. Sorry about that. :/ To get the Ant Farmer rank requires just a few minutes of playing around on the site.

Commenting has been disabled for this entry.