Ability to add comments to the Qt reference documentation ?
-
Hi everyone,
Don't know if this is the right place to talk about this idea, but I think it would be nice if we had the possibility to add user comments on the Qt Reference documentation, like they do for PHP, for example.
What do you think ?
-
I'm not thinking that adding user comments as it is done in PHP doc (function reference and a lot of comments after it) will be good for current structure of documentation. Maybe will be good to add button like "Show comments" to each method or each class, but don't know. From my point of view most part of questions are from using chain of 2,3,4,... different classes and user comments on one method (or even class) will not help in this cases.
-
Yes, comment should probably be hidden by default, with a link like: "show 4 comments". Also, ability to upvote comments should help filter signal from noise.
I agree that most questions are related to using several classes, and comments won't be very useful on those cases, that are usually largely documented in other places anyways.
But I think comments really have a lot of value to solve some very specific bugs / unexpected behaviors with the API. When you expect some method to behave in some way, and for some reason it doesn't. That would help developpers that are pulling their hairs on problems that take a whole day to solve, and would help the trolls find places where the API isn't as consistent / easy as it should.
I got this idea because I noticed that there is a very convenienent feedback link on each page of the doc. I used it twice and I thought : where is my feedback going? Who is reading it? Wouldn't it be benefical for other people to see it now, while the Qt team hasn't updated the doc to take it into account yet?
-
Hm, maybe you are right. As for me it will be good to have for each method in online doc link to code browser with this method opened.
-
Hi guys,
These are all good ideas! We have discussed these ideas as well, and I thought I'd dispense the conclusions we have reached.
The comments in the PHP documentation work very well for the PHP site. I've actually used it a lot myself when working with PHP and learned a lot from it. However, the PHP docs have a slightly different approach than we do.
- We currently push the documentation to different channels, not only the web. The content lives inside the Qt library itself and there way to contribute to this is through Git.
- We are planning to improve the number of examples dramatically - both complete examples and micro examples.
- Qt is launching this excellent arena, Qt Developer Network, for discussions and other related activities. I believe that this would be the right place for user comments.
This is why we - for now - have decided to leave user comments out of the documentation site.
On the subject of the feedback form - this information goes directly to our documentation team (and yes - we read it :).
Anyways, we really appreciate the feedback you give us. Keep up the good work!
-
Thanks for this information!
Just one question, while we are on the topic of the feedback form: should we use it to report very small things like typos, and stuff like that? Or would that generate too much amount of feedback?
Maybe it could be a good idea to have a posting guidelines for the feedback form.
-
Hi,
You can add Doc Notes after you've accumulated 181 points (http://qt-project.org/ranks )
In the meantime, if you find a mistake or have a suggestion, you can submit it at http://bugreports.qt-project.org/
