This issue is to advocate improved handling of comments once a reviser has incorporated them into the doc article, to encourage continued and happy participation of commenters, and better docs for readers.

In studying comments stats, I notice that there's been a custom to delete comments after they've been incorporated into an article's body, such as here: http://drupal.org/node/1461296

This is one of the few places where a valuable doc contribution seems to be lost without possibility of retrieval from history. It makes sense to hide comments that the reviser feels are no longer applicable, but it may well be the case that the reviser actually does not fully understand them, or expunged the details, and the comments would remain a useful perspective.

Further, the commenter who went to the effort of commenting may be chagrined that notes they thought they had made have vanished, and also that their contribution is no longer recognized.

So, an improvement would be a "comment from userX is hidden because incorporated" flag, which readers of the page could unhide if they wished.

A milder improvement would be to just edit the comments to indicate "incorporated by userX on dateX" or somesuch.

If it's really thought necessary to actually delete the comments, then replacing the comments with a comment that at least acknowledges them would be good: "Thanks to userA, userB and userC, whose comments have been incorporated into the article on [date]."

Also, if deleting comments is the practice, then it would be helpful if the comment form would note "your comment may be deleted by an admin once somebody has incorporated it into the article" so that users don't treat comments as a way to store technical notes dependably.

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Personally, I do not think we want to encourage comments at all on Drupal.org documentation pages.

When a documentation page has comments, it makes it difficult for people seeking "the right answer" to determine whether the page or the comments are correct, and also if the correct information doesn't get into the main page, some people wont' even notice the comments. This is why our current practice is to delete comments once the useful information in them is incorporated, and I don't think it should be changed.

What we really want people to do is click "Edit" and fix the page, rather than commenting. And I would hope that anyone who incorporates useful information from comments would also cite where the information came from in their revision log, like "Incorporated useful information from user_a, user_b, and user_c comments".

Adding a note to the comment form is a good idea though. I think it should say "Please don't comment. Just edit the page", as well as what you're suggesting. The problem is that this is only applicable to comments on doc pages, not to all comments, so it will require a bit of programming probably to accomplish.

Thoughts?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Component: Manage comments » Docs infrastructure
Issue tags: +docs infrastructure

And this is a discussion about docs policies and infrastructure, not a request to manage comments, so changing component.

jjkd’s picture

jjkd commented

I have to admit that this (the user should edit the page, not comment) is the first thought I had when reading this. Unfortunately, I suspect that in many cases the person who would be making the comment may not be equipped to make the appropriate changes.

That having been siad, I would agree that some kind of language added to the comment form encouraging editing the page rather than commenting would be good assuming the ability to comment is retained. I also agree that bening able to retain an audit trail of what comments had been made and the actions taken (and being able to hide that by default) would be better than deleting them.

wmostrey’s picture

wmostrey commented

I agree with #1 that we should encourage people to edit the page rather than leave a comment. This will indeed require a small bit of code to only have that message appear on the book content type. We could also add a more visibly statement on the top of documentation pages, much like wiki nodes on groups.d.o, for example http://groups.drupal.org/node/168009.

You are viewing a documentation page. You are welcome to edit it. Be bold!

I would still delete the comments though, not simply hide them.

The documentation page about incorporating comments already contains the message that "[t]he Log Message revision note should, if feasible, credit the person who provided the information" so that is covered already.

gwideman’s picture

gwideman commented

Responding to #1-#4:
I sympathize with the wish to have users integrate their additions rather than comment. I observe that this is not what users are accustomed to at many other tech websites, rather they see a custom to add technical notes in the comments.

Examples include the sites covering several of Drupal's constituent technologies:

http://www.php.net/manual/en/language.variables.php
http://dev.mysql.com/doc/refman/5.6/en/loading-tables.html
http://api.jquery.com/add/

Granted, these sites don't offer direct editing of their pages. However, I suggest that comments are not simply a second-class way to add info. Instead comments afford a more-inviting opportunity to add info because it avoids burdening the user with the need to integrate the new info into the existing article (jjkd's point), competently and while overcoming reticence about disrupting another's work. Indeed, often the added info is more akin to a useful footnote than a core topic, and hence appearing at the bottom of the article is actually appropriate.

I realize that assessments may vary on this; here I'm just hoping to give comments a good advocacy :-).

As far as credit to authors of deleted comments: I didn't realize there was a an instruction to credit authors in the log revision message. I checked the most recent 12 comments (searched for "Incorporated" in Manage Comments doc issues), and saw only one instance where that was done, so it does not really seem to be happening.

Again, opinions may vary on the importance of this. My view is that if one is trying to encourage quality and enthusiasm of involvement, then this is advanced by providing a vehicle that accepts the bite-size of contribution that users can readily provide (for many that's comment before full edit), and in a way that allows users to incrementally develop a personal identification with their contributed work.

To summarize this view: Comments are the gateway drug to article editing :-).

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

RE #5 - Those examples are all API documentation, where comments are being used to add examples, and the API docs themselves are generated from code (and are hard to edit). Correspondingly, on api.drupal.org we encourage comments.

The D.o Community Docs, on the other hand, are a different kind of thing, like a wiki where everyone can edit to get to the right knowledge being in the manual.

We've actually had this discussion before -- many times actually -- search old issues in the Documentation project issue queue and you can read those discussions. We've always come to the same conclusion, so ... I'm actually going to stop this discussion now and make an executive decision that we're not changing the policy now on comments.

But I do agree that we need to make the policy itself clearer, so I filed:
#1475172: Make comment policy clearer on Docs pages
Your help/opinions are hereby solicited on that other discussion as to how to make the policy clearer to people submitting comments.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Closed (won't fix)
gwideman’s picture

gwideman commented

> RE #5 - Those examples are all API documentation

OK, here are non-api examples.
http://www.php.net/manual/en/introduction.php
http://dev.mysql.com/doc/refman/5.6/en/choosing-distribution-format.html

jQuery: Amusingly, it turns out that non-api pages have [Edit] links (and no comments facility). However to edit the page you must have an account, but the login page provides no way to actually create an account. I found an issue report: "The wiki is currently not open to public signup as we have been having problems with spam and most of the content in our MediaWiki is planned to be moved to other destinations. If you'd like to help with docs or otherwise, please follow up here and let us know what you were trying to edit, for the time being." Hmmmm.

> We've actually had this discussion before -- many times actually --
> search old issues in the Documentation project issue queue

I will do that soon.