Integrate issue queue and pages: disable doc comments

Connecting the issue queue and the doc pages crossed my mind a few weeks ago. I was actually planning to discuss it in the planning sprint but I completely forgot about it and as you know, I didn't have the opportunity to do so. :-( This issue made me remember a suggestion I was thinking of.

IMO, commenting on handbook pages is already obsolete. I think it was necessary before because users cannot edit the page and their way of correcting it is by commenting. Now that a user can edit pages, they can make necessary changes to a page directly. If users have concerns that they cannot incorporate directly to the handbook page, then probably creating an issue instead of commenting is more ideal. What if the link at the bottom of the node isn't "Add new comment" but "Create an issue". There should also have a block (in the content region?) listing all open issues regarding the page they're viewing. If you're in the issue queue, there should also be a way to see if it is connected to a particular handbook page.

It's actually almost the same as your suggestion, the difference is that I am thinking of disabling comments in book pages all together and encourage creating issues instead.

I think integrating a smart create issue link on doc pages would be fine. I think that link would would need to populate some field on the issue form with a reference to the document.

Until this functionality is in place, I don't believe we should turn off commenting in docs because it is a way from someone to ask for more explanation or point out something confusing. Oftentimes, someone can point out something confusing, but yet not know how to improve upon it for lack of knowledge. I do think the open editing fixes many things, but there is still a role for comments, until we can get smart links that will open new issues.

(p.s. great job on finding and removing those no longer needed comments!)

Shai

Yeah. The suggestion is not meant to just disable the comments. The intention is that the creating of issues will replace commenting, so disabling of comments will only happen when the issue queue is integrated.

Quoting Lee from #2:

Either you fix the problem yourself or you create a proper issue (rated by priority etc). It doesn't make much sense to leave an important comment on a page in the hope that someday, someone will stumble upon it and do something about it.

Chatting with kkaefer at the doc sprint in Stockholm about this and it should be pretty straightforward to add a link with hook_link in drupalorg.module and use prepopulate module to send people off to create an issue with some bits prefilled for them. The main stopper on this is to get prepopulate module in shape for use on drupal.org #252053: Allow admins to hide prepopulated fields

So we need to get that knocked out, and then a pretty small patch to drupalorg.module and we should be good. Moving to webmasters queue for more eyes and eventual implementation.

After thinking about this issue for quite some time, I think it would be easier and faster to "hard code" that feature into drupalorg.module. Essentially, we'd have to implement a form_alter hook for the node form and overwrite three fields (title, body and tag so that we can list the issues tagged with the handbook page we're referring to later). That way, we could even "autodiscover" the information by using the referrer.

I don't know what shape http://drupal.org/project/prepopulate is in, but in general, my experience maintaining project* over all these years is that if there's a viable contrib module that does what we want, we should use it, instead of rolling our own. The more "we should just hard code that into foo" decisions we make, the harder it is to port foo to the next version of core when it's time to upgrade *.d.o. That's bad enough when foo == project itself (which now has a modest and growing user-base off d.o), it's even worse when foo == drupalorg.module, which by definition is only used here.

Also, are people proposing to use issue tags to remember what node(s) a given doc issue is in reference to? That seems like a bit of a hack, and it's going to require yet more hacks to do the sorts of features people are proposing here (a block of issues for a given handbook page, and a link on issues back to the page(s) they refer to). Seems like that aspect of this proposal needs more thought.

The one we have at api.d.o is okay, I guess. It goes: "Buggy or inaccurate documentation? Please file an issue instead of commenting here. Need support?" The link prepopulates the node title of the issue with "Documentation problem with (title of referring node)".

Closing this as a duplicate of #810508: Kill handbook comments