Review "Commenting on handbook pages and API pages"

Updated title and component to make it clearer what you are looking for.

I would volunteer to do this, but I disagree with allowing comments on api.drupal.org in the first place, so I would probably get mad and just want to remove all of them. :)

I think monitoring the comments (and removing spam btw. ;) ) to improve the documentation would perfectly fit in with the things i'm already doing on d.o itself.

I would be more than willing to help moderate comments on api.drupal.org

I support any of the three people who've offered, and think they would do a great job.

jhodgdon: You will learn to love them, I promise. ;)

I don't already have any higher access to d.o, but I would love to help, as I would have a lot more bumps on my head if it was not for api.drupal.org and think comments are on api.d.o is a great idea.

webchick: Not sure I volunteered. :)

I will volunteer for this. I think the comments on API are great, the ones on php.net have saved me countless times.

jhodgon, yes, you did volunteer. You replied to a thread calling for volunteers, and since you were the first one, it made you seem very eager. Webchick came across this thread and assumed, as I do, that you are standing by to help out. ;)

Oh, and BTW, comments on api.d.o. are incredibly cool. Take this one, for example. We never would have known this if commenting wasn't enabled. http://d6-api.drupal.org/api/function/db_placeholders/6

Senpai: I fixed the title and component of the issue, because I regularly monitor the Doc issue queue, and the component was incorrect. I did not volunteer to monitor comments, which you would know if you read my comment.

I do still think comments on api.drupal.org are a bad idea, just as they are on the handbook on drupal.org. If there is information that should be in the doc, than the doc should be fixed, and to do that on api.drupal.org, you file an issue and make a patch. Having comments is just inviting people with an easier way not do do the right thing. That's my opinion. So I would tend to delete all comments. I don't think you want me to monitor comments. Get someone to monitor comments who thinks they are a good idea.

In the specific case you cited, there are 8 functions calling db_placeholders that all offer examples, linked right there, and I don't think this comment provides a better example than those 8.

Count me in.

Sorry my wording was unclear. :(

drumm: One other thing you might want to put above the "add a comment" section is that if someone needs support, they should ask questions in the forum and not by posting a comment on api.drupal.org. Or perhaps give a link to the Support page on d.o: http://drupal.org/support

The reason I suggest that is that in my experience in tediously wading through the comments on Handbook pages, they are roughly equally divided between suggestions for how to improve the page (where they should have just edited the page or filed an issue) and things that should have been in the support forums.

OK, a few times over a few years I've commented that I'd really like to see API comments - so now that it's happening I would like to help out.
I guess we'll have pretty much the same policy as existing handbook posts - though I'm all for enforcing it a lot more strictly.
- No Questions, removed with extreme prejudice.
- Only answers, explications, examples and maybe links to the handbook or see-also.
- no threading (?)

I really love the php.net comments for the use-cases and real code examples they provide. They have shortened my dev time in many cases. We have the advantage of the "n functions call func()" cross-referencing (invaluable sometimes) but user-contributed snippets with annotation are just great - for my way of learning anyway.
Looking at the quality/usefulness of posts on php.net, I guess their moderations is 'approval needed'. On d.o we've always tended the opposite, but we need to be ruthless in trimming stuff that's not directly constructive.

(I'm currently doc contributor on d.o, but not a comment moderator, dunno if that makes a diff)

I volunteer too.

could we get a link to http://api.drupal.org/pages-with-comments in the user menu?

We can add it in the doc menu block, next to the handbook pages with comments. I think the user menu isn't appropriate.

perfectly acceptable ;)

I made some changes to http://drupal.org/node/14345 to make sure it covers API comments as well as Handbook comments.

However, several items on the list of "valid" comments surprised me. Actually, most of them surprised me. Here's the current list:

* Providing links to modules, blogs, and relevant articles.
* Links to forum posts with new information directly related to the handbook or API page.
* Links to similar content in the handbook, or links to inconsistent content in the handbook.
* Comments that provide useful facts that should be included in the handbook page.
* Noting errors in the documentation or corrections to incomplete information.
* Complete re-writes of the handbook page.
* Content that should become a child page of a handbook page.
* Noting dead links.
* Terminology recommendations, including inconsistencies and terms which new users may be unfamiliar.
* Suggestions to clarify text for new users.
* Recommended re-organizations and outlines of handbook pages or handbook sections.

Any thoughts on which of these should actually be considered as valid comments, rather than being recommended to file as issues?

Sorry, drumm. I reset my browser cookies and caches all the time, so that may have been the problem. Please try again:

http://api.drupal.org/user/1366

Ah, I was logging into d6-api.drupal.org before. Thanks for sorting things out, drumm.

@#21: There are some typologies of comments that surprise me as well.
I would think that comments about dead links should be reported as bug, which is what the text before the comment fields report.
I would also remove the reference to modules in providing links to modules, blogs, and relevant articles; truly, I would leave only the reference to relevant articles, meaning any book pages present in Drupal.org.
Also the complete re-writes should be reported in a different place.

So really, what do people want to see in Handbook and api.drupal.org comments? I am not sure the two answers are the same. It seems to me that extra links and examples on Handbook pages should go into the Handbook page. With a.d.o, they might be appropriate as comments.

Thoughts?

Cheers!
While half of that list of reasons to comment is outdated (child page, rewrite etc) with the current permission set, I don't think that we need to prohibit off-site links entirely. Yes, it leaves a small gap in the policy regarding spam posts, but there ARE some good tutorials from lullabot, drupaldojo, and I know that I never would have been able to learn about the batch API without a bunch of offsite examples from other blogs.
As long as the link is genuine, I don't think it's an automatic strike out.

Hey, is there a reasonable way to do any of the following:

* Mark a comment as reviewed.
* List comments that have not been reviews.
* Menu item to this page. (either in top bar of api.d.o or in the doc block of d.o.)

I know there are only a few comments now, but I see it possibly getting a little out of hand, and these things would help review comments more efficiently.

As far as the handbook page for commenting, I think the ideas are the same, but it might be beneficial to have a separate page since the context is very specific and separate. But, I also don't think most people will actually read this page, and therefore it just becomes a page to cite in the case of disputes.

On the same path, is there a way we could get a more prominent callout to support? I've deleted 3 support questions today alone. I realize it's going to be inevitable, but I think the callout for "Buggy/inaccurate documentation?" is much stronger than the one to the support page, and it seems like people are going to be much more likely to ask for support, than to complain about the accuracy of the documentation (since it is typically quite accurate).

Anyway, just some thoughts. Great work so far drumm, and everyone else involved.

I *love* the "Buggy or inaccurate documentation? Please file an issue instead of commenting here. Need support?" It works, and it's a good idea to have that sort of text there.

There might be an easy way to address the "need support?" part. Change "Post new comment" to "Post an example". Then, in the textarea, use jQuery to insert the string "Do not use this form to ask questions about Drupal". See http://morten.dk/form/contact for a visual example by the king himself.

Links to similar content in the handbook, or links to inconsistent content in the handbook.

For a function documentation page, similar content would probably be understood as documentation pages for similar functions.
Would not it better to have a book page for the comment that is possible to leave in a book page, and one for the API pages comments?

My point above (#21) was that almost NONE of the situations currently listed on http://drupal.org/node/14345 are situations where someone should be commenting on a Handbook page. I think almost none of them apply to api.drupal.org pages either. (That page dates back to the days when almost no one had priveleges to edit Handbook pages; now, everyone can edit most Handbook pages.)

Which is why I asked in #21 if someone could list the situations where we would welcome comments. Maybe we should separate that into (a) Handbook and (b) API, if they are different. And once those are listed, someone could update the page that says when comments are OK.

I'm not seeing the handy link to the pages-with-comments in the "Documentation team links" block yet. Am I supposed to?
It took me heaps of searching just to find my way back here to this page where the link was mentioned (partly due to the issue title change :-)

So, after trying to moderate a few comments, I have some questions:

1) Is there any easy way to notify the user that their comment has been removed or edited so that they can learn form their mistakes?
2) What about wrong information, if it is corrected later in the thread? For example: http://api.drupal.org/api/function/l/6#comment-78 I have made a post that explains why the person is wrong, but do I just delete their comment (then goes back to 1 question)?

--
zzolo

See http://drupal.org/node/287927, which reports a template to use when deleting a handbook support comment.

2) that specific one is tricky. I would've posted an comment remiding users to t() their link texts if they're providing them harcoded, and would've pointed to t() -- afterwards, i woud've send a message to the user.
(note done here (yet), as this probaly creates some discussion here, and everyone can review it now.)

OK. Someone posted this issue:
#576964: Examples in the API Doc
asking "Why can't I post examples?"

I am assuming they tried to post an example in a comment, and the comment was rejected (on api.drupal.org).

Do we have a policy?

There is no link on api.drupal.org to the policy about comments, as far as I can see.
I don't see anything in http://drupal.org/node/14345 that says that you can't put examples in comments, or says where they should go.

???
Maybe someone who understands the policy can respond to that issue, and politely tell that user what the policy is?

I don't think comments with example code are not allowed; if those comments are not allowed, then what kind of comments could you write?

Well, maybe someone with comment delete privs could respond to that issue and get more information about what happened and/or what the person is complaining about?

Dammit. I don't want to, but OTOH think we should :
Remove fluff comments like "Thanks"
eg:This helped a ton! Thanks!

:-(
To keep the reference material clear of chaff, this adds nothing of value technically ... yet in the world of blog-commenters it's possibly a good etiquette thing. How can I tell someone off for saying thankyou? :-/

Thoughts?

RE #38 - Examples are Gooood and encouraged. Need more feedback from the poster on that issue.

I would also like to point out that the comments name the users, but those names are not links, so it makes it an extra step to contact these people about removing their comments.

To remove thank you comments, from what I understand when I asked earlier is to just contact the user to explain that Thank you comments are awesome, but not really helpful in the grand scheme of things. This is a template for support questions: http://drupal.org/node/287927 , but the idea is the same.

As far as examples, I thought that was the major point of adding comments.

As for #576964: Examples in the API Doc, there is a chance that I removed it without notifying the user (before I posted my question).

--
zzolo

Another issue coming up. So, I contacted Frank about this issue:
http://api.drupal.org/api/drupal/developer--topics--javascript_startup_g...

It is mostly helpful, but I think he can move some points to the issue queue. How should we keep track of handling things. I want to give him a chance to fix it, but it would be annoying if we all messaged him (not knowing what the others are doing).

Thoughts?

--
zzolo

How should we keep track of handling things.

Drupal.org webmasters queue has already a component for api.drupal.org; we could use that, if we want.

let's see if that works ;)

I was not talking of this task report.

IMO, having rolled a few comments in the docs pages, I can assure you there is great 'mileage' to get out of thank-yous.

Before I get blasted... I completely agree that thank-you's don't need to be in the comments.
HOWEVER, you need to provide a way for folks to say thank-you.
We did have a doc survey on how to say thank you this past summer, which might provide more insight.

What message do you send to the Drupal community if you delete positive feedback and respond to it with a hand-slap not to do it again.

@bekasu
I know what you're saying, but the docs are not a blog or guestbook. I LOVE php.net documentation moderated annotations and think we should be aiming at that. php.net would be much worse if it had a bunch of "Thanks, that solved my problem" comments in the middle of its useful examples.
I don't want to tell anyone off for being polite, but I also don't think that hanging on to such comments has any value for others unless the comments have long-term utility. If we could just archive them or expire them after a period, or demote them to a "3 users found this comment helpful - see feedback" sort of feature... I don't think it's worth building myself, but it's the only polite way I can see that working.
Maybe an alternative would be to make it easier to "send message to the commenter" instead of post message for the world to see. :-/

Yes, i was thinking similar: "3 users found this comment helpful", just without the see feedback.
I always liked that of other sites, as it also allowed you to pick some quality posts out of it.

dman and alexanderpas..

You have my complete agreement.
Someway to pass on the 'good vibes' without creating clutter would be glorious.

In the survey, it was pointed out that the author of the doc may be long gone and it is actually the subsequent editors who provided the 'added value' to the original page. Again, difficult to tease that out of the log.

How about a short-term solution (either a button to thank the author privately or a timed-delay delete) and a long-term solution (3 users found this to be helpful)?

I don't see the need for the short-term solution, when the long term solution will be in place.

Perhaps I'm missing the obvious. The long-term solution of '3 people found this helpful' is already in place? Could you point that out to me? I'd love to start integrating that when I roll comments on pages.

Comment #51 is not clear to me too; I don't see any solution being in place, at the actual state.
Maybe alexanderpas meant that it would be better to think to a long term solution, rather than thinking of a short term solution. Or at least, that is the only interpretation I can give to his sentence.

hope i clarified the post, if we have a long term solution, i see no need for a short-term solution.

ahh soo..

My little heart was hoping for a drupal pony!

hey - it seems like this all got set up - can we close this issue, or do you want to leave it active for communicating more about the api comment moderation?

I still think there is much more that can be done to make this a much easier process, but in reality, it's not like there is a high volume of comments. Closing.

sounds good to me - i mean, the ideal would be some system to say +1 on a comment, and it's pretty well acceptable to delete thankyous and what not when the comments are rolled in. maybe post-redesign there might be a place to think about this further...