Add notes + points
-
Having thought about it a bit more why should a documentation error not get noted on the page? Why get filed away on some other bug tracker where it might get fixed eventually when as a note on the page it can directly help those who are viewing said page?
-
... blatantly spamming up a thread just to gain some fast points is really, really in poor taste and is not the kind of thing that should be encouraged...
The problem is that is was directly encouraged. I wanted to post a note on a doc page which was the big feature blogged about. After creating an account I didn't have enough points. While I did spend ten minutes doing good stuff I only had a few points and more than a hundred to go with no way to get them. Clicking on the points page it tells me exactly what to do to get the most number of points to get me to 180 so I did just that. As I created a new thread (with a legit first comment btw) and only grinded on my own thread, I am not sure I can classify it as spamming either. The system told me what I had to do and I did it.
Really the problem is that basic functionality is several weeks of normal usage away and "180 points" a poor way of stopping bots.
-
[quote author="Gerolf" date="1309373030"]I think it could be stated on both: JIRA and doc note, but JIRA is a must, doc not an option, right?[/quote]
Wouldn't it eventually be the other way around? Wont the doc guys be monitoring the notes to incorporate and improve docs based upon comments?
On this topic I really doubt developer.qt.nokia.com accounts work on jira which will stop a log of people right there from reporting things
-
[quote author="icefox" date="1309373409"]Wouldn't it eventually be the other way around? Wont the doc guys be monitoring the notes to incorporate and improve docs based upon comments?
On this topic I really doubt developer.qt.nokia.com accounts work on jira which will stop a log of people right there from reporting things[/quote]
good point, should also go as suggestion to JIRA, as that is the stuff to report bugs and suggestion which should not be forgotten.
I'm not sure if the doc people are monitoring the doc notes on dev net, I hope so. But writing a JIRA entry is not the worst idea. :-)
-
You can do so very much with a rich documentation site on the admin side of things. Their should be data mining out the wazzoo! The owners of modules (or anyone who want them) should get notifications of notes so they can be incorporated back into the docs (email, rss, tweat whatever). You can generate reports on what doc are used over and over (bad api, bad docs?) Users who search/visit for X also search for Y used to guild. What about referral links? Most links to QFooBar might be from examples and blog entries that would be perfect bottom of the page fodder or even for review to determine if that is a major missing part of the docs. I was actually really bummed to find that the Add Note was per class and not per function as that will jumble things up quite a bit, but adding notes was still a big plus.
Most of the time when I (user hat) have a doc fix I want to make a clarification on a function description or add a link to another class/function you might want to use. The rest of the time they are small errors. A typo, broken link, spelling error. Small enough to matter, but absolutely not big enough to go through the hassle of a full blow bug reporting system.
I think I might have confused the above goals with what might have only been a move to the nokia way of documenting things. The built in ability to comment might have been a nice bonus not the focal point of the move.
-
[quote author="icefox" date="1309376166"]You can do so very much with a rich documentation site on the admin side of things.[/quote]
This is very true, and what you see now is "only the beginning" as they say. However we do need to prove a certain level of success before we can enlist the support of the devs. Maybe one day we can skip JIRA for bugs in the documentation, just have them as notes and as they get fixed the notes are removed. This is how the FAQs are maintained now btw.
As for bottom of the page fodder - that is coming! :) Here is a sneak preview: http://dl.dropbox.com/u/217336/related_02.png Things selected based on tags and other factors, by the Qt Content Robot currently in assembly.
-
(Frustrated rant about having to sign up just to discover I can't even comment without getting site-specific UselessInternetPoints removed).
I've filed a bug in JIRA, since I can actually do that without first having to go spam random forums / vote-up random pages.
https://bugreports.qt-project.org/browse/QTBUG-40586#comment-251940
Please link to that from http://qt-project.org/doc/qt-4.8/qsqlerror.html with a note along the lines of:
"Application developers should generally avoid directly parsing error messages, as they may vary based on locale, database system version, etc. Usually the framework would offer access to the underlying database's standard SQLSTATE error code but QSQLError does not present this information at time of writing. A future revision of the QSQLError class may hopefully address this issue. In the mean time application developers should not attempt to differentiate between error types, such as "serialization failure" or "column does not exist", beyond the information provided by the type() method.".