When using the link Add new comment on any of the Community Documentation pages on Drupal.org, a message is shown near the top that looks like so:

Is your comment an addition, problem report, or example? Instead of adding a comment, edit the page content directly. If you are unsure of the correct edits, add a comment here and then edit the page to update the page status. Once a solution for the page has been agreed upon, edit the page accordingly and read incorporating comments on how to remove the related comment(s).

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 may be removed at any time.

If you wonder why that message is there, then go have a look at the comments below various community pages, such as the "Read documentation" links mentioned (within "Resources") on the project page from these contributed modules:

Obviously, those comments don't comply with what's mentioned on Commenting on community documentation pages and API pages, i.e.:

... if you have a question about how to use a function or perform a task being described, please use the Forums or one of the other Support options, rather than adding a comment. And if you want to report a software bug, file an issue instead of adding a comment somewhere.

So what can people, who contribute to a contributed module's documentation via such Community pages, do to:

  • discourage the creation of such comments?
  • cleanup such comments?

Note: I'm aware that there are modules (also in the top 10 of reported installs) that have a "Read Documentation"-link on their project page that is not somewhere on drupal.org, but that's not what my question is about (I don't want to consider links outside drupal.org).

up vote 1 down vote accepted

If you know of such Community documentation pages that are at risk (or already suffer) this problem, then perform these steps:

  • For anything "valueable" in such comments, find a way to include them in the documentation pages themselves, or create an appropriate issue for it (so move it to where it belongs).
  • Report such comments for removal (where appropriate indicate what you did in the prior step).
  • Wait for all comments to be removed.
  • Post your own (new!) comment to such page, which looks something like so (XYZ = machine name of the contributed module that the documentation relates, ABC = name of the module, 987654321 a node ID that fits for you):

    • Subject:

    Use XYZ issue queue for issues about ABC

    • Comment:

      Please do NOT add comments to this page or any of its childpages to report issues (feature requests, problems, etc) about the ABC module. Instead of adding such comments, please create an issue in the <a href="/project/issues/XYZ">ABC issue queue</a>.

      <em class="marker"><strong>Note</strong></em>: Refer to <a href="/node/987654321">this page</a> within these documentation pages of an example of various comments that do not belong there. The content of that page is very valuable community docu, but most of the comments below it do not add any value to that page (and are not compliant with the content of the yellow message you get when adding a comment).

  • Occasionally go check (visit) those pages again. For any additional (new) comments: repeat the first 2 steps above.

For an illustration, have a look at this comment (Disclosure: I posted it) ... So far it seems to work ...

PS: Comments to improve / correct / extend the content of such community documentation pages are fine. After they got processed (via some type of edit of the page ere needed), they should get removed again (as in step 1 and 2).

Your Answer

 
discard

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.