Doc Notes - We Have a Vision
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.
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.
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!