Follow-up to #1472448: Better handling of incorporated comments

Our D.o community docs policy on commenting is outlined here:
http://drupal.org/node/14345

However, this is not clear to people who add comments.

So we need to:
1) Add something to the sidebar of docs pages to make it clear that comments and page content will be edited/removed to build the best docs possible from available information.

2) Add something to the comment form on docs pages to make it clear that (a) it's preferable to just edit the page if you know the right answer (b) link to http://drupal.org/node/14345 for details of the policy. (c) don't use for support, use the forums. (d) comments will be removed if not providing useful info or when their info is incorporated.

Suggestions for exact wording/mechanism of (1) and (2) are most welcome -- and is there anything else we need to make clear?

CommentFileSizeAuthor
#11 1475172-doc-comment-policy-v3.patch4.74 KBjhodgdon
#8 commentdisclaimer.png26.47 KBjhodgdon
#7 1475172-doc-comment-policy-v2.patch4.43 KBjhodgdon
#6 sidebarblocks.png51.46 KBjhodgdon
#5 1475172-doc-comment-policy.patch4.35 KBjhodgdon

Comments

mollyavalon’s picture

mollyavalon commented

Here's a suggestion for the sidebar. This might be a tad too long.

Got a comment?

  • Is your comment an addition or edit or example? Please edit the page content directly. Comments are removed after edits are made, so skip the middleman and do it yourself.
  • Is your comment a question or request for support? Take it to the forums. Comments are not answered here, and comments not providing useful information are removed.
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Nice! This sounds like a good thing to add for (2) [near or in comment form] rather than on the sidebar though. Our docs sidebars are already pretty busy... for instance, see:

http://drupal.org/node/1310466

For the sidebar, I was thinking more along the lines of a short sentence to add to the copyright block at the bottom, which currently says:

Drupal’s online documentation is © 2000-2012 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License.

mollyavalon’s picture

mollyavalon commented

Oh whoops, I conflated 1) and 2). So yes, what I wrote above could work for the comment form.

But given the busyness of the sidebar and the very legalese look of the copyright block, do you think anyone would even read an additional sentence there?

How about this?

Comments on documentation pages are used to improve content and then deleted.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Agreed, no one will probably read the sidebar. Your addition looks good. :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
StatusFileSize
new 1475172-doc-comment-policy.patch4.35 KB

Here's a patch that alters the copyright block and the other block on the Documentation landing page, and also (hopefully) adds a disclaimer similar to #1 to the comment submission form (only if you are commenting on a documentation page).

I'm attaching it here (completely untested). Next step will be to apply the patch to my test box, test it there, and get feedback.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Assigned: Unassigned » jhodgdon
StatusFileSize
new sidebarblocks.png51.46 KB

Here is the revised right sidebar on the Documentation landing page, generated by the patch in #5, for review. This shows the revised Doc landing page block (above, only slightly changed), and below is the copyright block that appears on every doc page (with addition of a sentence about comments).

The comment form stuff in the patch above needs work; I'm working on it and will report back with a new patch and some screenshots when it's working.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
StatusFileSize
new 1475172-doc-comment-policy-v2.patch4.43 KB

Here's a new version of the patch... One more test and I'll post a screen shot...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Make comment policy clearer » Make comment policy clearer on Docs pages
Project: Documentation » Drupal.org customizations
Version: » 6.x-3.x-dev
Component: Docs infrastructure » Code
Status: Active » Needs review
StatusFileSize
new commentdisclaimer.png26.47 KB

OK, I think the patch in #7 is working. What it does:
a) Revises the block on the right sidebar of Documentation landing page slightly (see screenshot from #6, top block).

b) Adds a sentence to the bottom of the copyright block on all docs pages (see screenshot from #6, bottom block).

c) Adds a "Please read" section to the comment form. I have verified that it only appears when you are commenting on a Book page (at least, I verified that it doesn't appear when commenting on a Forum post or Issue), and only when you are adding a new comment (not when you are editing an existing comment). See screen shot attached to this comment.

Reviews of the code or of the text I added would be welcome... I have tested the code and I think it is working properly.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

For those who cannot read text in images and would like to review...

Here's the text of the first block (Documentation landing page block):

Help maintain the Community Documentation

The Drupal.org online Community Documentation is written and maintained by the Drupal community. When you are logged in, you can:

Edit most Documentation pages by clicking "Edit" at the top of the page.

Add new pages by using the "Add child page" link at the bottom of the page. Check the Documentation issue queue for new page requests by others.

Leave comments to report problems on pages (also edit the page to change the page status).

Create Documentation issues to request new documentation and make moderation reports (inappropriate content).

Here's the text of the copyright block:

Drupal’s online documentation is © 2000-2012 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License. Comments on documentation pages are used to improve content and then deleted.

Here's the text added to the top of the comment reply form on book pages:

Please read...

  • Is your comment an addition, problem report, or example? Instead of adding a comment, edit the page content directly. Or, add a comment here, but be aware that comments are removed after page edits are made.
  • Is your comment a question or request for support? Take it to the forums. Comments are not answered here, and comments not providing useful information are removed.
dww’s picture

dww
we/he/they
commented

- Is this intended?

Leave comments to report problems on pages (also edit the page to change the page status).

I thought the point was no one's following comments on doc pages, so why would people report problems that way?

- Channeling yoroy/bojhan: re "Please read..." I don't think that's going to fly. ;) a) we've been stripping "please" and b) I think you'd want this block to appear in a div with class "warning" or something if you actually want to draw attention to it. Or something. I dunno, that just seems a little hokey somehow. ;)

- I see the patch is doing s/spam or inappropriate content/inappropriate content/ -- is that intentional? It's not mentioned here.

Otherwise, the patch looks good.

Thanks,
-Derek

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
StatusFileSize
new 1475172-doc-comment-policy-v3.patch4.74 KB

RE #10 (in reverse order):
- Forgot to mention the spam thing. We've been trying to unify the spam instructions on #1472428: Reconcile spam report instructions the last few days to say to report spam to webmasters not documentation queue, so I brought this text in line with those recommendations.
- Agreed on the "please read". But lists need a header before them and I didn't know what to put there. I guess it could be changed to "Before submitting your comment:" and the language adjusted. I'll make another pass.
- Yes, we want to encourage people to just edit the page, but not everyone who notices a problem has the answer or is a competent writer. So an alternative is to leave a comment while changing the page status to "needs technical review" or something else similar. We just can't get around having that as an alternative. I will change "also edit the page" to "be sure to edit the page" though, to emphasise the importance of changing the page status. Not that anyone reads the sidebar on the Docs landing page probably anyway, but best to at least have a clear message if they do.

So... Here's a new patch. After attaching I'll apply it to my test box, and make some new text dumps for review.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

OK, I think I like this better. It is a more unified message about comments (I think/hope), and doesn't use "please". :) I also took out all clarification of what a moderation report is, because I think it wasn't really necessary. For your review....

Top sidebar block on Documentation landing page is now:

Help maintain the Community Documentation

The Drupal.org online Community Documentation is written and maintained by the Drupal community. When you are logged in, you can:

Edit most Documentation pages by clicking "Edit" at the top of the page.

If unsure of edits, leave a comment instead, and edit the page to update the page status.

Add new pages by using the "Add child page" link at the bottom of the page. Check the Documentation issue queue for new page requests by others.

Create Documentation issues to request new documentation and make moderation reports.

The copyright block is the same as the last pass:

Drupal's online documentation is © 2000-2012 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0. PHP code is distributed under the GNU General Public License. Comments on documentation pages are used to improve content and then deleted.

The comment form text is now:

Note:

  • Is your comment an addition, problem report, or example? Instead of adding a comment, edit the page content directly. Or, if you are unsure of the correct edits, add a comment here, and then edit the page to update the page status. Be aware that comments are removed after page edits are made.
  • Is your comment a question or request for support? Take it to the forums. Questions are not answered here, and comments not providing useful information are removed.

EDIT: And just as a note, "forums" is a link in the comment form; there are several links in the copyright block (just as there are currently, those haven't changed), and the only link in the first block is to the docs issue queue.

michelle’s picture

michelle
she/her
Primary language English
Location Wisconsin, USA
commented

Why are we stripping "please"? Have we decided to no longer be polite? That seems strange to me...

To be honest, I find "Help maintain the Community Documentation" to be a bit off-putting. It sounds more like a command than just informing the person that they can help out, if they wish. Maybe something like "How you can help with the Community Documentation"? Probably too long for a title, though...

If unsure of edits, leave a comment instead, and edit the page to update the page status.

I don't see that line on the actual page. Possibly I'm seeing a cached version? If that is going on the page, I suggest merging it in with the line before as it doesn't make sense as a stand-alone line. Also, "If unsure of edits" doesn't sound very clear to me. I know what it means but it may be unclear to some.

Michelle

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Here's the page to look at the changes:
http://docs-infra-drupal.redesign.devdrupal.org/documentation
(htaccess login : drupal/drupal)

If you want to log in to see the comment form, use ariatest/ariatest

Regarding please... see
http://drupal.org/style-guide/content#voice
http://drupal.org/node/604342

dww’s picture

dww
we/he/they
commented

Michelle -- yeah, we decided the interface text in our software, and by extension our flagship website here, should be emotionally heartless and cold to better reflect the computers that power them. ;)

Seriously though, yeah, it's been a concerted effort by the UX team in both D7 core and on d.o to genearlly stop saying "please". See Interface text under the User interface standards for details (it's the 2nd point).

michelle’s picture

michelle
she/her
Primary language English
Location Wisconsin, USA
commented

Sorry, when you said, "Top sidebar block on Documentation landing page is now:" I somehow missed that meant on the dev site. I should have realized that. Whoops. :)

As for "please", I completely disagree but this isn't the place for that so I'll let it drop.

Michelle

dsquaredb’s picture

dsquaredb commented

The revisions to the comment policy in #14 are clear and concise. I think they should be understood by everyone, including those new to docs and commenting.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Reviewed & tested by the community

Thanks for taking a look! Given that the code is working, and at least one person has weighed in to agree with the wording, I think I'll mark this RTBC. If anyone else comes to review and disagrees, feel free to set it back.

drumm’s picture

drumm
he/him
Location NY, US
commented
Status: Reviewed & tested by the community » Fixed
Issue tags: +needs drupal.org deployment

Looks straightforward enough, committed. I did change the quotes back into real quotes.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

That's fine! I just don't have an editor that can handle them. :(

Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Oh and as a note... the "real quotes" that were there before were not very good. They all pointed to the right (close quote) instead of [left]quoted thing[right]. So hopefully if you put the "real quotes" back in, you didn't just put the bad ones that were there back. I thought that ascii quotes were better than the bad ones that were there?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

sorry, ignore #21, I just wasn't looking at them sufficiently blown up, and got confused by the font.

drumm’s picture

drumm
he/him
Location NY, US
commented
Issue tags: -needs drupal.org deployment

Deployed.

Automatically closed -- issue fixed for 2 weeks with no activity.

  • Commit b279baf on 6.x-3.x, 7.x-3.x-dev authored by jhodgdon, committed by drumm: 
    [#1475172] Make comment policy clearer on Docs pages