Doc Notes - We Have a Vision

by Alexandra in Qt DevNet News (30199 views)

Some time ago, when we first started talking about integrating the Qt documentation into the Qt Developer Network, Marius pointed me to the PHP documentation to explain what he had in mind. What I found was a huge collection of additions to the reference documentation provided by The PHP Group. In fact, in many ways, these additions are the documentation.

Why we added the notes feature

While the Qt documentation clearly ranks among the best, the former, more static way of presenting it misses out on a big opportunity. Just like you, thousands of experienced programmers visit our class references every day; you use Qt in a large variety of settings, to achieve very different things, and you all know a lot. You have your trusted solutions, little tricks and favorite use cases.

Our trusted expert writers are working hard on their part of the documentation, but we believe that when you join their efforts by adding notes to class references, we will get much, much further.

What we think could make good doc notes

Everything that is relevant to the specific class you’re looking at can be captured in a note. I can think of further explanations on what to use the class for, code snippets that show what a certain class can do, and how it is implemented. It could be hints to common traps, and clever solutions. Links to tutorials on the wiki or forum threads that cover a related topic could prove useful in cases where you need more background or are still learning to use the API.


Doc Note

And then there are code examples: those more extensive code snippets that you can compile and learn from. They add context to pure documentation and provide more detail than a class reference can. These code examples are immensely useful to those who are making their way into Qt land.

Stealing with pride

Let’s take a look at an example from the source of our inspiration, the date function overview in the PHP documentation The official part is straight forward and serves its purpose well. PHP users however felt the need to add some more (ok, a lot more) context to the function.

PHP notes

Now, I am not a php developer—or any kind of developer, for that matter—but I can instantly see how useful this can be. Searching around in the notes gives a n00b like me important pieces of information that would probably spare me a lot of headaches, and which is apparently missing from the “official” documentation.

Did you notice how much valuable content has accumulated in these notes over a course of 12 years? It’s quite significant. Of course, expecting it all to be brilliant would be expecting a miracle: some notes are not quite ideal.

So, in order to make sure that the best doc notes show up at the top we have applied all our content QA measures: as with almost all content items on the site, you can rate them up or, in this special case, report them by rating them down.

Ready to go?

I hope I shed some light onto why the doc notes exist, and where we want to take the Qt documentation. What do you think? What kind of notes would you add to the documentation? And as usual, we’re open to suggestions for improvements. Let us know in the comments!

Picture of CreMindES

March 22, 2012

CreMindES, Lab Rat

I welcome this improvement, and I know this was on topic for quite some time now. I’m happy to see that notes can be added, especially code snippets. Keep the good work guys :)

Picture of Morten Engvoldsen

March 22, 2012

Morten Engvoldsen, Lab Rat

Getting the same feature into the developer tool chain is key. The reason the PHP-docs are so complete with comments is that it lives in the tool that the programmer uses. As long as the comment feature doesn’t make its way into the SDK, I’m afraid that it won’t reach the desired goal.

I know you know how to do it ;)

Picture of androssofer

March 22, 2012

androssofer, Lab Rat

I love the php docs! they are the best around, and if you are replicating them then that is epic!

Picture of Ivan Čukić

March 23, 2012

Ivan Čukić, Lab Rat

Really cool idea.

Sometimes the notes are tied to specific methods – it could be useful to add something like

  1. QString & QString::append ( const QString & str )
  2. ...
  3. See also: operator+=(), prepend(), and insert().
  4. 15 notes by Qt Community

and when you click the ’15 notes’ you are pulled down to the notes and only those for QString::append are shown.

Picture of Alexandra

March 23, 2012

Alexandra, Hobby Entomologist

Ivan, you’re on to something. ;)

I was toying with a similar idea, it’s definitely something to look into. However, it might be impossible to add this into the documentation source where it would have to live somehow. If that was possible we would have a solution for the tool chain issue that Morten mentioned as well.

Picture of Matt Williams

March 23, 2012

Matt Williams, Lab Rat

Are there any plans for community-contributed comments to be integrated into the documentation proper? This way it will be available in offline readers etc.

Picture of msjen

March 24, 2012

msjen, Lab Rat

One of the things that I like about the notes/comments/tips in the PHP docs is that one can see how other folks are using said function. This would be wonderful for the Qt docs, as it would help connect the doc information with what folks are already contributing to in the wiki and expand, over time, how various elements and properties could be used.

Picture of Alexandra

March 26, 2012

Alexandra, Hobby Entomologist

Integration into the documentation might be tricky. At some point we need to have a sit down with the team in documentation and look at the options.

Picture of francomartins

May 8, 2012

francomartins, Lab Rat

PHP is really very interesting .

Picture of rkcherukuri

June 6, 2012

rkcherukuri, Lab Rat

I guess this is very good imporvement and interesting to see this every qt documentation …

Commenting has been disabled for this entry.