Problem/Motivation

We would like to turn off comments on Documentation pages (see #810508: Kill handbook comments). The reason is that people use comments mostly to report problems on doc pages, but it's not a manageable way for the Docs team to notice the reports and fix them.

Proposed resolution

Instead, we'd like to have:
a) A link at the bottom of each Doc page to report an issue (which would pre-fill a few fields so it prompts people to report a good issue).
b) A list of "related issues" on the sidebar of each doc page, so people could see what's being discussed about that page.

In order to do (b), we need issues to have a way to be "related" to a doc page. That is, issues need to have a nodereference so that we can say "this is an issue on this particular doc node".

Details:
1) Project issue nodes would have an optional, multiple-valued CCK noderef field, with a reference to Book pages, called "Related documentation pages". It would be displayed in a collapsed fieldset by the same name.

2) This field would be editable via comments, the same way as you can now update other issue meta-data when you add a comment.

3) This field would be settable via the URL query field when the issue is initially filed, the same way you can now for other fields (title, component, category, etc.).

4) Documentation/handbook pages on d.o will have a block view listing open issues that have been marked as related to that page. It will only be shown if there is at least one issue with a noderef to the page.

5) UI for where this appears on (a) file issue form (b) comment form to update via comments and (c) issue display is TBD.

Remaining tasks

So far, no actual work implementing this has been done.

Some implementation ideas can be found in comment #4 and #12.

User interface changes

New field on Project Issue. New block on Documentation pages.

API changes

None.

Original report by jhodgdon

We would like to have a nodereference field added to issues for the Documentation project. The idea would be that when we file issues in the Documentation project, they could be marked as to which page in the Handbook they pertain to.

Once that has been added, we would want the automatic issue filing link from
#810508: Kill handbook comments
to automatically fill in that field with the correct noderef.

Also, we would want to display a block on each Handbook page of the issues that have been filed against that particular page.

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Priority: Normal » Major

I'm upping priority on the highest-priority issues for docs team infrastructure.

dww’s picture

dww
we/he/they
CreditAttribution: dww commented

Sounds like a good plan. Some questions on the details:

A) Can this noderef be changed by comments, or is it only set in the original issue node itself?

B) Is it multi-valued, or a single reference?

C) The reference only links to book pages, right?

D) Do we add code in drupalorg* somewhere to hide this field for all issues unless they're in the main documentation queue? What about contrib documentation issues? It's going to be confusing as hell for most people if this field is always visible. I'd like to keep it fairly hidden by default. See #1023108: Make issue tags less visible by default and link to the documentation on how to use them for example.

E) Where exactly on the node add form UI (and, depending on A, the comment form) does this field go?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

RE #2:
a) Hopefully by comments as well as on the original issue, otherwise it's kind of useless. It would be ideal if it could be set by node/add/project-issue URL as well, the way you can with the other issue fields.
b) Multi-valued would be best. We definitely have some issues that pertain to multiple book pages. And optional, as some issues may not pertain to a specific page.
c) Yes, reference only to book pages for purposes here.
d) I think drumm was thinking it would be hidden for issues outside the doc project, and he had some idea of how to do that, when we discussed it in Vancouver. No idea what that idea was.
e) Details, details, you want details? :) OK, I guess we need to think about that now.

dww’s picture

dww
we/he/they
CreditAttribution: dww commented

Re: A) I *think* there's code in project_issue to let you alter any CCK field you add to an issue node via comments, just like the default fields. However, I haven't tested that in ages, so I don't know if it works at all. If not, we either have to fix that, or see if we can get this working via http://drupal.org/project/comment_driven and add that to the mix. I have no experience with comment_driven, but I've heard good things. If that pans out, I'd happily just make that a requirement for project_issue in the future and rip out all the internal code that's handling this functionality some day.

Pre-populating via GET when first adding the issue is probably going to require a drupalorg_project_form_alter() since I don't know what else would be responsible for doing this.

B, C: Makes sense, and in line with what I was assuming.

D: Probably drupalorg_project_form_alter() again. One edge case here is what if an issue starts life in the docs queue and has some noderefs, and is then moved to another queue where the refs would be hidden? Probably the logic should be something like this pseudo code:

if (!$in_docs_queue && empty($issue->doc_noderefs)) {
  // hide it
}

So, always show if we already have some doc references, regardless of the queue it's in...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

D/E: Hmm. Maybe if the noderef was called "Related documentation pages" it could be useful for more than just the Documentation issue queue? Certainly in the Drupal Core queue, related doc pages come up a fair bit. And I can see it being useful for contrib projects too, if someone wants to report an issue against the doc component of that project, related to some doc in the Handbook about that project.

So maybe the UI could just be a collapsed fieldset, and have it visible for all projects?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Just suggested something similar for forums:
#1027608: Use forum to make Discussion tab/block for Book pages

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

This issue is now holding up
#810508: Kill handbook comments
since we've decided we can't deploy the latter until this issue is addressed.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I'm somewhat in the dark about what would be necessary to make a patch to add this feature to d.o:

a) I don't think we currently have CCK on drupal.org, right? How would we get this added? (and/or Comment Driven)?
b) Once we have CCK, what would we need to do to define this field and add it to the Issue node type (in a collapsed fieldset) -- use Features or otherwise export the content type, and then add it in code? If so, where?
c) Any ideas about how to make it visible/invisible on certain situations - form_alter hooks or CSS or what?
d) If we make the View for the block that shows issues related to a page, do we just export that and add it to a module somewhere?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

For reference, here is a compilation of the discussion above, regarding specs for what we want this to do (open to further review/discussion/refinement of course):

1) Project issue nodes would have an optional, multiple-valued CCK noderef field, with a reference to Book pages, called "Related documentation pages". It would be displayed in a collapsed fieldset by the same name.

2) This field would be editable via comments, the same way as you can now update other issue meta-data when you add a comment.

3) This field would be settable via the URL query field when the issue is initially filed, the same way you can now for other fields (title, component, category, etc.).

4) Documentation/handbook pages on d.o will have a block view listing open issues that have been marked as related to that page. It will only be shown if there is at least one issue with a noderef to the page.

5) UI for where this appears on (a) file issue form (b) comment form to update via comments and (c) issue display is TBD.

pwolanin’s picture

pwolanin CreditAttribution: pwolanin commented

At some point there were a few non-book pages in the handbook, though not sure that really matters.

pwolanin’s picture

pwolanin CreditAttribution: pwolanin commented

I don't see CCK or Noderef as being in the d.o codebase yet, though I know it's part of the plan. They are installed on other sites like security.d.o, so I'm guessing they have passed any needed security audit?

Updating via comments might be added to the drupalorg.module code or maybe a little custom module - this is the module that allows updating taxonomy when you comment, which is similar:

http://drupalcode.org/viewvc/drupal/contributions/modules/comment_alter_...

dww’s picture

dww
we/he/they
CreditAttribution: dww commented

Re: #8:

a) #651484: Enable CCK and node_reference

b) The issue node type is provided directly via project_issue.module. So, I don't think we can use features to export the whole content type. That'd be better, but I don't think that works. You could try it out on your dev site. ;) Probably we'll just have to click it together via the CCK UI to add the other field to the existing content type. If it works as a feature, we'd want it in http://drupal.org/project/drupalorg -- there are other proposals floating around that would involve adding Features to drupalorg, but AFAIK none of them have actually been implemented yet.

c) I'd definitely go with form_alter(), from either the feature module or drupalorg_project

d) Yes, all views on d.o should be exported to code. Again, either in the feature if that works, or in drupalorg somewhere if not.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Assigned: Unassigned » jhodgdon

Thanks dww! I'll see what I can do.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Note: A separate feature would be to have a link at the bottom of doc pages to file an issue. Thoughts about this are actually on #810508: Kill handbook comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Just added an issue summary.

drumm’s picture

drumm
he/him
Location NY, US
CreditAttribution: drumm commented

I started the buildout of a dev site for this called docnoderef. Sorry, I haven't tried any punctuation and am just assuming it might not work. It should be done within 30 minutes, I'll update this issue if not. Details on how dev sites are set up are at http://drupal.org/node/1018084.

Be sure to move this issue to http://drupal.org/project/drupalorg if ll the code ends up there.

davidhernandez’s picture

davidhernandez
Primary language English
Location USA
CreditAttribution: davidhernandez commented
Assigned: jhodgdon » davidhernandez

Looking into this.

drumm’s picture

drumm
he/him
Location NY, US
CreditAttribution: drumm commented

Making a new dev site called issue_noderef. Should be done in 30 min or less.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Active » Postponed

I'm postponing this. The current plans for #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. have us not using the Docs issue queue for the community documentation at all. When we get to the curated/managed docs, we will probably want to revive this, but in a different form.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Postponed » Closed (won't fix)

It's definite -- we're not using issues, so this is a won't fix.

So we don't need the issue_noderef test site for this issue. However, we do need a site for this other issue
#1027608: Use forum to make Discussion tab/block for Book pages
so if we can keep this test site for that issue, that would be lovely!

EDIT: I already commented on that other issue that whoever takes it on should use issue_noderef to develop, so if that is not OK with infra, please go comment there.

drumm’s picture

drumm
he/him
Location NY, US
CreditAttribution: drumm commented

The issue_noderef dev site has been removed.

drumm’s picture

drumm
he/him
Location NY, US
CreditAttribution: drumm commented
Issue summary: View changes

Add issue summary

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Closed (won't fix) » Active

Reopening

Mixologic’s picture

Mixologic
He/Him/His
Primary language English
Location Portland, OR
CreditAttribution: Mixologic commented
Project: Drupal.org infrastructure » Drupal.org customizations
Version: » 7.x-3.x-dev
Component: Other » Code

Not sure what's needed since this was re-opened, but Im going to put it in the customizations queue as part of the infrastructure queue cleanup.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Project: Drupal.org customizations » Documentation
Version: 7.x-3.x-dev »
Component: Code » Docs infrastructure

This does not belong in that project. It is an open request that is in front of the D.o Software Working Group. Do they have their own issue queue?

For now, I'll move it to the Documentation project...