Problem/Motivation

Documentation pages currently allow comments, which are mostly used to report problems in pages. But when people do that, it is difficult for the Docs team to follow up by fixing the problems, and difficult for readers to figure out what's correct and not correct in the page (plus they may be reading incorrect information if they don't read all the comments).

The other main use people make of the comments is to ask support questions. That is also not good, because support people don't see the questions there.

Proposed resolution

Encourage people to file issues instead of leaving comments to report proplems, and provide a way to see what issues are open on a page (see issue #995292: Noderef field on issues for Documentation project).

Encourage people to get support via the support forums or other channels, by directing them there (sidebar box or bottom-of-page box). We might also want to do #1027608: Use forum to make Discussion tab/block for Book pages

Once that is done, turn off the ability to add new comments.

Remaining tasks

a) Resolve #995292: Noderef field on issues for Documentation project. This issue is postponed until that is done.
b) Add text/link to direct people to the support forums for support (or to the more comprehensive Support page?). See also #1027608: Use forum to make Discussion tab/block for Book pages.
c) Turn off new comments on doc pages.

User interface changes

No more ability to add comments to doc pages. New links to add issues and get support.

API changes

None.

Original report by arianek

Oh, how I hate the handbook comments. To sum up, they are impossible to manage in an effective way, as far as helping on support requests, or updating reported bugs about the page content. The issue queue is much more useful... But how to integrate issues with the handbook pages?

Pondering this with some folks on IRC, and with the Docs g.d.o group (on this thread: http://groups.drupal.org/node/70983) I propose the following as a fairly simple but effective solution that would allow us to do away with handbook comments permanently:

  1. Add a field on the docs issue http://drupal.org/node/add/project-issue/documentation form for a referenced d.o NID (to reference the handbook page the issue is about)
  2. Build a view block for the handbook pages that displays any issues related to the page on the handbook's page (to make it easy to see issues filed related to the page if you are reading the handbook page).
  3. Icing on the cake would be to put a link somewhere on each handbook page that says something to the effect of "Questions or comments about this page? Please file an issue", which would take them to http://drupal.org/node/add/project-issue/documentation and pre-populate the NID of the handbook page they clicked the link on with the node.

Potentially related issues:

#651484: Enable CCK and node_reference
#569552: Provide a mechanism for issue meta discussions

(If this should be somewhere other than the redesign queue, feel free to relocate. I'll ping dww for input, as I understand he's been doing a lot of thinking about these things.)

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

rfay’s picture

subscribe

add1sun’s picture

Definitely a good idea. I have been thinking about this in the new docs.d.o site for a while, so the main thing we'll need to work out is that the issue queue and d.d.o will be on separate sites. We'll have to build the view across this gap. I'm not sure if/how bakery and such might let us do this.

arianek’s picture

oh snap. that does make it trickier...

joachim’s picture

Subscribe.

Point 3 is probably actually the easiest to implement right now. Add it as a node link just alongside 'add a comment' and we might dissuade a lot of people from adding a comment there and then!

drumm’s picture

Issue tags: -drupal.org redesign

Not going to tackle this in the redesign

drumm’s picture

Project: » Documentation
Component: Documentation » Other documentation issues
silverwing’s picture

Here's an old issue in the Webmaster's Queue #413882: Integrate issue queue and pages: disable doc comments

arianek’s picture

Issue tags: +docs infrastructure

adding tags

jhodgdon’s picture

Title: How to kill handbook comments » Kill handbook comments
Project: Documentation » Drupal.org infrastructure
Component: Other documentation issues » Other

OK. We have a definite proposal now, as output of the Vancouver docs meeting:

a) Turn off comments for all existing and future Book Page nodes.

b) Add a "File an issue" link, similar to what is currently on api.drupal.org, to the bottom of every Handbook page. The text there is "Buggy or inaccurate documentation? Please file an issue instead of commenting here. Need support?", and we could use the same text except exclude the "instead of commenting here", because we won't have comments.

c) If you click on the link, you should get an issue with the following defaults:
- Title: Documentation problem with (URL of originating page)
- Project: Documentation
- Component: Correction/Clarification
- Category: Bug report
- Priority: Normal
- Status: Active

I'll file a separate issue about some of the other ideas, but this is the immediate need.

I also kind of realize this is two separate requests, but they need to be done together.

jhodgdon’s picture

lisarex’s picture

When we turn off comments, we should set them to 'read only' so that docs folks are still able to incorporate the useful ones into the node body. Eventually :) :) they can be disabled for good!

arianek’s picture

totally concur on that lisa

arianek’s picture

totally concur on that lisa

jhodgdon’s picture

OK, here's a revised proposal:

a) Set comments for all existing Book Page nodes to "read only" so that people can continue to roll comments in, and doc admins can continue to delete them, but no one can post any more comments.

b) Set comments for all future Book Page nodes to "disabled", so that no one can post any more comments.

c) Add a "File an issue" link to the bottom of every Handbook page. The text should read:

Does this page need attention (innacurate, incomplete, need editing, etc.)? Please [link]file an issue[/link]. Need [link]support[/link]?

File an issue link URL:

http://drupal.org/node/add/project-issue/documentation?title=Documentati...

Support link URL -- should link to the Community and Support page shown in top nav:
http://drupal.org/community

Hmmm... On (c) do you think this should go somewhere else other than the bottom of the page, like in the sidebar?

jhodgdon’s picture

Oh, and just as a note: in #14, PAGE_URL_HERE in the file an issue link should be replaced with the page URL that the link is coming from. :)

arianek’s picture

and d) a sidebar block on the handbook page showing related issues (or are we leaving this for later?)

joachim’s picture

> Hmmm... On (c) do you think this should go somewhere else other than the bottom of the page, like in the sidebar?

Good idea. Then d) can go in that block later on.

Also, this would help (or even resolve perhaps) #956816: Visually differentiate the documentation section.

jhodgdon’s picture

RE #16 - that's on a separate issue, because it requires a field be added to the issues (noderef for the page it references).
#995292: Noderef field on issues for Documentation project

arianek’s picture

re #18 gotcha.

re #17 agreed! (re: sidebar - would go well with the "issues for the page" block) just needs to be obvious since people will be like wtf no comments?

jhodgdon’s picture

OK, revised proposal, incorporating comments above:

a) Set comments for all existing Book Page nodes to "read only" so that people can continue to roll comments in, and doc admins can continue to delete them, but no one can post any more comments.

b) Set comments for all future Book Page nodes to "disabled", so that no one can post any more comments.

c) Add a "File an issue" link to every Handbook page. The text should read:

Does this page need attention (innacurate, incomplete, need editing, etc.)? Please [link]file an issue[/link]. Need [link]support[/link]?

File an issue link URL:

http://drupal.org/node/add/project-issue/documentation?title=Documentati...
(with PAGE_URL_HERE replaced by the current page URL that the link is displayed on)

Support link URL -- should link to the Community and Support page shown in top nav:
http://drupal.org/community

d) If possible, this link would be on the sidebar. If not possible to put it in the sidebar for some reason, the link would go at the bottom of the page.

e) Once we get #995292: Noderef field on issues for Documentation project, we would also put a block of Related Issues on the sidebar of each page. Hopefully just under this link, because they kind of tie together.

lisarex’s picture

The plan in #20 looks good but perhaps minor amendment to the phrasing... could just say "Does this page need revising or updating? Please [link]file a Documentation issue[/link]."

Not sure that we should link to the Community & Support landing page. It can't possibly address whatever frustration they were experiencing. I'd leave it off :)

arianek’s picture

I'll +1 #20 with lisa's amendment in #21. If we don't link to the Community page, I would suggest we add on:

Need support? Try the <a href="/forum">Drupal.org Forums</a> or ask for help on <a href="/irc">IRC</a> in the #drupal-support channel.

jhodgdon’s picture

I agree with Ariane that we need something to address "Do you need support?", because a lot of the comments on the pages have been support questions, and it seems like sending people to appropriate channels would be polite. What we don't want to do is encourage people to file their support questions as issues in the Doc queue.

joachim’s picture

Seems to me that expanding this beyond just one line of text would be a good idea, so people spot the bit about 'need support?'. Maybe put that first too!

So a block that says:

Need support? blah blah...

Problem with this page? yada yada...

jhodgdon’s picture

Hmmm... Maybe we should rephrase this:

Have questions about this page? Ask in the (link)Forums or in (link)IRC.

Does this page need revising or updating? (link)File an issue.

arianek’s picture

Mmm, getting close! Revisions:

Need more support on this topic? Ask in the (link)Forums or on (link)IRC.
Does this page need corrections or updates? Please (link)file an issue.

(And because I like personalizing, I would add something like "Thanks! - Your favourite (link)Docs Team" or some equally friendly signoff to make it more personal, but I doubt anyone else will +1 that part!)

jhodgdon’s picture

My suggestion in #25 was to not use the word "support". My reasoning was that there is already a Community and Support link in the header of d.o, and maybe people don't realize that "asking questions" is the same as "support", leading them (currently) to add comments to the pages and file issues when what they really need is to use the forums or IRC. Keep in mind they may have landed on the particular page via a Google search.

So how about:

Have a question about this page or need more support? Ask in the (link)Forums or on (link)IRC.

Does this page need corrections or updates? Log in and then edit the page or (link)file an issue(endlink).

(link)Join the documentation team(endlink)
[that link would go to d.o/contribute/documentation]

arianek’s picture

How about "Need more help on this topic?" ...? Rest +1 on #27

lisarex’s picture

I think we're really close :)

How about:

"Need more help on this topic? Ask in the (link)Forums or on (link)IRC.

Does this page need corrections or updates? Edit the page if you're logged in, or (link)file an issue(endlink).

Want to contribute to documentation? (link)Learn more about the Documentation team(endlink).
[that link would go to d.o/contribute/documentation]"

arianek’s picture

capitalize the T in Team and that has my seal of approval ;)

jhodgdon’s picture

+1 from me too.

joachim’s picture

+1 from me.

jhodgdon’s picture

That looks like enough +1s. Revised proposal, incorporating comments above:

a) Set comments for all existing Book Page nodes to "read only" so that people can continue to roll comments in, and doc admins can continue to delete them, but no one can post any more comments.

b) Set comments for all future Book Page nodes to "disabled", so that no one can post any more comments.

c) Add a new block to every Handbook page, containing:

***
Need more help on this topic? Ask in the Forums or on IRC.

Does this page need corrections or updates? Edit the page if you're logged in, or (link)file an issue(endlink).

Want to contribute to documentation? Learn more about the Documentation team.
***
The link in the second line would go to:

http://drupal.org/node/add/project-issue/documentation?title=Documentati...
(with PAGE_URL_HERE replaced by the current page URL that the link is displayed on)

d) Once we get #995292: Noderef field on issues for Documentation project, we would also put a block of Related Issues on the sidebar of each page (that's discussed on the other issue).

So... What else do we need to do to make this happen? Does someone need to write the block code -- looks pretty straightforward to write (all it needs to do is plug the page URL, probably sanitized, into the file an issue link).

Bojhan’s picture

It seems I am one of the first here to question this, but are we not losing a whole lot of valuable comments?

1) Do we know how valuable our readers find it?
2) Can we provide equal to larger value by removing comments?

To me it seems like the value they provide is often more than the annoyance of support requests put into comments, if its unmanageable thats something to work on - removing the functionality sounds rather drastic. Excuse me if all this has been considered before, but the step towards putting up in a comment is much lower than starting a forum post or issue (especially the latter).

arianek’s picture

Hi Bojhan - This has indeed been considered, but I'll summarize the rationale behind it just for transparency's sake.

From the docs team perspective (and it's docs team who's been seen as responsible for managing the comments), we're really doing readers a disservice, as they end up posting mainly suggestions of changes to the page or additional information (both which should just be made as edits or issues filed accordingly), or asking for support regarding the topic the page is about.

Because nobody is monitoring these pages, mostly they just get ignored, and people never get the support they need or have their changes to the page done. There are nowhere near enough people working on managing and rolling in (then deleting) the comments to actually make a dent in keeping up with them.

It's not that we don't want to manage the change/support requests - we do, but it's not feasible through the comments.

We want to make it easy to post a related issue by creating a link straight to the docs queue, which automatically nodereferences the docs page (and also this allows us to show a list of related issues right on the docs page, so people can see if others have posted similar comments/issues). And pushing people looking for support into the forums or better yet, IRC, is really important, as their requests are really unsupported currently.

I know I may be repeating things here, but aside from magically finding a hundred or so people to manage comments consistently, this really is by far the best option we've come up with.

Bojhan’s picture

Alright, thanks for the explanation! As we implement the solutions to solving those problems - lets make sure we evaluate after a while if we meet the desired value for our readers. I feel moving from comments to forum posts / issues has some issues with centralizing feedback/questions - I will give feedback as soon as there are screenshots.

arianek’s picture

Sure, thanks Bojhan - happy to have your input. We are hoping to keep the issues centralized by having any issues noderef'd to the page show in a block on that page's sidebar as well, so that it's easy to look through anything related (currently there's no way to do this), but we're not anticipating doing this for forum posts atm.

joachim’s picture

One technical point that has me scratching my head -- how will we handle the fact that *all* issues have a noderef field for handbook nodes, not just those on the Documentation component?

arianek’s picture

i think drumm was planning to hide them everywhere else (and that only refs from issues to book nodes would be done anyway)

uNeedStuff’s picture

I think doing this leads to clarity. You have a suggestion you go here, you have a question you go there. Clear. I do think that each page is going to need it's own que, and the ability for someone to take ownership of a page is easy to do. Right now it's not clear, and I think the steps to taking ownership of a page, and how long until a change can be applied should be stated somewhere. I personally just did this. I added a comment to suggest a change, and then when looking for something else found the issue que for the page, or what I think was the issue que for the page, I'm still not sure if I found the right place even then.

arianek’s picture

@uneedstuff you did find the right place ;) but most people certainly don't file an issue noting their comments though, so they really do get lost a lot of the time! - we are actually considering assigning sections of the handbook to be managed by individual docs team members or smaller groups, but there isn't a structure yet to do this (we may get part of the way there with this nodereference functionality though!)

but at least with these changes, yes each page will get sort of a mini-issue queue for it on its page, so it should help keep everything tied together better.

jhodgdon’s picture

Status: Active » Needs review
FileSize
2.12 KB

OK. #33 is still the plan... Here's a patch for the drupal.org project that I think will generate the correct block for the Handbook page [patch for contributions/project/drupalorg/drupalorg_handbook/drupalorg_handbook.module, function drupalorg_handbook_block() ]. I hope I haven't violated any guidelines in the drupalorg system - it seems like the Handbook module blocks don't follow the same standards as the ones in the drupalorg.module file, as far as when to put URLs in directly and when to take them out and use the url() function.

I'm not sure about the other settings, needed in #33 - presumably these are config and not in code?

jhodgdon’s picture

Project: Drupal.org infrastructure » Drupal.org customizations
Version: » 6.x-2.x-dev
Component: Other » Code

Since the patch in #42 is against the drupalorg module, I'm temporarily moving this issue to that queue.

If the patch is accepted, we still need to make some configuration changes, as outlined in #33. This patch only addresses item (c) from that plan. But there's no reason this patch couldn't go in before the other config changes are done (anyway I would suspect the block would need to be turned on).

jhodgdon’s picture

Priority: Normal » Major

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

Jeff Veit’s picture

In my opinion, one of the key reasons that PHP became a successful language was the ability of users to add comments to the handbook, so I think it's essential that we don't lose this facility. The PHP handbook became a repository of all the best PHP knowledge, with the little snippets of info in comments often providing invaluable help.

What I think we need are better tools for managing the info in comments. Here's a possible scenario...

A flag next to a comment could let people tag as support. If a comment gets 3 support flags in 2 days, then it doesn't belong in the handbook, and could be automatically posted to support.

Similarly a flag that indicates that this is a page enhancement suggestion should bump the comment into a queue if it's clicked often enough.

If the comment is valuable, then a like flag could indicate that it should be bumped into the body.

If the comment is older than 3 months then it's a candidate for automatic removal to a wikipedia style 'conversation about this article page', but I think that comments less than 3 months old (maybe even 6 months?) should still be attached to the handbook page itself. At the bottom of the comments on the page, a Read More should take you to the continuing conversation.

jhodgdon’s picture

smoothstr: We are not taking comments off of the API site, which is api.drupal.org, which is the place analagous to the PHP documentation.

We are talking here about taking comments off of pages in http://drupal.org/documentation. See above for all the reasons we are doing this -- but basically, if the comments are correct, they need to be incorporated into the pages -- and anyone can edit most of those pages directly by clicking Edit at the top of the page. If they're support requests, they should be in the forums. If they're issues (or the person doesn't want to edit at that moment or has questions), they should be filed as issues rather than lost in the comment stream.

joachim’s picture

> The PHP handbook became a repository of all the best PHP knowledge, with the little snippets of info in comments often providing invaluable help.

Urgh, which you have to pore through to find something in the dross -- no thanks.

Just like in code, and perhaps more so, refactoring is essential in documentation.

Jeff Veit’s picture

Title: Kill handbook comments » Remember we have different levels of user

Long-time users and core people will have no problem editing the pages.

Beginners will almost certainly feel that they shouldn't, even if their contribution is valuable.

We need to support both. By taking away comments on pages, you are removing an opportunity for new users to contribute. Instead of taking away the ability to contribute, make sure that there are tools to manage the contributions.

@#42: Joachim, the core useful stuff gets incorporated. But I've been saved hours and hours at times because of a comment that someone has left. Like 'In v5.2.3 this doesn't work as advertised. Instead ...' That's not something that belongs in core documentation because it's transitory. But it's definitely something that belongs in the documentation.

Bojhan’s picture

Title: Remember we have different levels of user » Kill handbook comments

We do not use, title to make an argument.

jhodgdon’s picture

New users will still have the opportunity to create issues, which is what is taking the place of comments. They will even be given a link that will make them an issue, where all they will need to do is fill in the description that they would have previously put into a comment. And, the information they want to contribute will be in the issue queue, where we can deal with it, instead of being lost in a sea of thousands of comments, where we can't manage it.

And, when we get
#995292: Noderef field on issues for Documentation project
taken care of, we will also have on each page a list of the issues related to the page, so people can go and look at and comment on the issues.

As we've discussed extensively above, we have a completely broken "system" right now. Yes, anyone can comment and it's a low barrier to contributing, but the "contributions" are for the most part not beneficial to Drupal documentation. We would like to redirect this to a method of contributing that will be beneficial.

Can we get a review of the patch in #42, and please get it in?

joachim’s picture

> Beginners will almost certainly feel that they shouldn't, even if their contribution is valuable.

We're lacking in a Wikipedia-style 'be bold' culture, yes. But that's another problem.

jhodgdon’s picture

Do you want to comment on the plan in #33 or the patch in #42 and see if we should change the wording so as to encourage people to be more bold (in an appropriate way of course)?

laura s’s picture

Just discovering this issue. (We have lots of separate issue queues!)

This change is pretty radical, and I'm not sure will be too helpful. What this will do is (a) discourage people from contributing helpful contextual information, and/or (b) balkanizing helpful info. Usually the comments offer helpful tips or other approaches — sometimes dissents or warnings that something is not in best practices — and those will largely be lost or rendered invisible to readers of the documentation. I've personally found comment threads extremely helpful in understanding more fully a piece of documentation.

This also forces the (false) notion that there is One Way for each thing, and that there's no room for discussion.

Personally I feel this is a feature that may serve the Documentation team but probably will not serve the end user. Maybe I'm wrong, but color me skeptical.

-1

jhodgdon’s picture

I'm sorry that a few people are so worried about losing comments on pages in the official on-line Drupal documentation. Again, I will once more try to present the arguments we used in coming to the conclusion that this is what we want to do:

a) Roughly 95% of comments are either support questions or wrong, and that doesn't even count the spam.

b) The purpose of the documentation pages is not the same as the purpose of support forums. The purpose of documentation pages is to present correct information, not to discuss what the correct information is.

c) Having these types of comments on pages is detrimental to end users, because they have to wade through information of questionable quality in order to figure out the right answer they are seeking, and may not know enough to be able to judge the relative merits of the body of the page and the comments, or have the time to read through a long support thread.

d) The documentation team cannot keep up with the volume of this type of comments that are being added to the pages, to peruse and remove the bad ones and incorporate the few helpful ones. It is a huge and never-ending task that is getting in the way of us being able to do more interesting and valuable tasks.

e) The plan here (see above) is to provide a helpful block directing people to use the forums or IRC for support questions, and either edit the page or file an issue (along with a link to file the issue that does everything for them except type in the description, which is presumably what they would have added as a comment) if they think there is something wrong or missing from the page. I don't see how this is a much higher barrier to the user than hitting "reply" and typing in a comment. It's just a link that happens to take them to a different page to file their question or comment.

f) If the information gets into the issue queue, we [doc team] can actually evaluate it and/or add it to the page and/or discuss whether it's correct or not.

So. Again, this issue is open to discussing the merits of the wording proposed in the patch in #42, which is also noted in the plan in #33.... No one has bothered to even review that apparently, which would be most helpful.

silverwing’s picture

My concern is for contributed projects. Do we want all support requests for, say, Facebook Connect to go through the Documentation queue before being moved? Or are we going to come up with a template to use on those projects with links to appropriate queues?

jn2’s picture

Maybe I can provide a beginner's perspective. Drupal.org is vast. I'm only now beginning to figure out how parts of it work. This change to docs will make it easier for new people to find and use different parts of d.o. - the issue queues and support forums. The proposed links effectively remove barriers to participation and will ultimately help new people get more out of d.o. sooner.
+1

dww’s picture

The patch in #42 is broken. $arg[1] is a string, not an int. You need is_numeric() for this to appear. See attached.

The only other potential problem I saw is there's no title for the block when it's rendered, since there's no 'subject' field in the array we return in the 'view' case for this delta. Is that intentional?

Overall, I'm +1 on removing comments from handbook pages, given the actual reality that the doc team keeps explaining in this issue. So, once I hear clearly whether or not we want a subject on this block, I'll commit and deploy.

Cheers,
-Derek

arianek’s picture

@silverwing

of course it would be ideal to have the template support linking to the contrib queue (perhaps this can be a future improvement for this). in the meantime, at least with the sidebar block of related issues, it'd be fairly easy for contrib maintainers to see issues there too.

i think we'll want contrib projects to manage their own docs if they're able - we can recommend that they all have a "documentation" component to their individual issue queues. if they don't do that, certain projects aren't well maintained, or beginners who don't know that would exists come to the main docs queue, then docs team will continue to manage any other contrib issues as effectively as possible. (this is basically what we do right now, if there's a big issue with docs for contrib, i usually try and move the issue to their queue for input.)

this is making me realize, we still need to refine how we work with contrib as far as docs go, so this will be possibly a separate issue to start and discuss, but at the very least, we ought to reconsider an initial plan to only surface this noderef field for docs issues - it may well be very useful to keep it surface for contrib as well.

@lauras

do you have an alternate suggestion of how to manage these then?

it's *really* not realistic or effective how the comments are managed right now (which in the end also is not serving the end users). docs team doesn't have the resources to manage, roll in, delete comments on all the many, many pages, especially as the community and amount of docs grows. in my view, it's either this or we put a disclaimer like "the content in the comments below is not endorsed or monitored by the documentation team. if you need support, please post in the forums; if this page is incorrect, please edit it or file an issue in the documentation queue." and then just offload our responsibility.

but to me that is far worse - the number of comments will just grow and grow, and they will continue to be unmonitored, which means not solving any of the issues we're trying to deal with here.

dww’s picture

Status: Needs review » Needs work

Just had another thought about this patch. It only adds a block. However, a) from the plan in #33 should also be automated via drupalorg_handbook_update_N(). We're sure as hell not going to manually click through all the existing book pages to set them read-only. ;) While we're at it, the update can disable comments on new book pages (b). In fact, the update could also enable this new block in the right region for bluecheese (the rest of (c)). @see drupalorg_update_6500() ;)

So, definitely needs work for 33.a. Optionally needs work for 33.b and the rest of 33.c (although those are only a few minutes each of clicking around in /admin, so those could be left for manual effort after this is deployed).

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

Yeah, I was wondering how the turning off comments was going to be taken care of. Agreed it needs to go into this patch. I'll work on that, as well as enabling the block, and thanks for the reference to drupalorg_update_6500().

Regarding a title for this block -- I am not sure whether we want one, or whether a title would be OK with the design parameters for d.o. The idea is for it to go on the right sidebar on pages like:
http://drupal.org/getting-started/before/overview
It would go between the navigation and the copyright block. The copyright block currently has no title, so I assumed this one shouldn't have a title either. Thoughts? Do we have design guidelines I should reference?

dww’s picture

Re: setting comments to read-only:

db_query("UPDATE {node} SET comment = %d WHERE type = 'book' AND comment != %d", COMMENT_NODE_READ_ONLY, COMMENT_NODE_DISABLED);

Or, because update_sql() is so evil and stupid:

update_sql("UPDATE {node} SET comment = 1 WHERE type = 'book' AND comment != 0");

Re: title for the block: there's no design guideline about this that I know of. I think it's just case-by-case if a title helps break up the sidebar and add clarity to the grouping of the text, etc. Maybe drumm knows otherwise. ;)

joachim’s picture

> i think we'll want contrib projects to manage their own docs if they're able - we can recommend that they all have a "documentation" component to their individual issue queues.

I'm pretty sure we already recommend that contrib projects have a "documentation" component in their issue queues; at least they have one by default.

jhodgdon’s picture

I was talking with esmerel on IRC and we came up with a possible block title:
Next Steps

I still need to make another patch. I think I'll see about setting up a sandbox.

dww’s picture

+1 to "Next steps". If y'all stick with that, please use that as the delta for the block so it's all more self-documenting. Thanks!

lisarex’s picture

Seems good to me! +1

laura s’s picture

do you have an alternate suggestion of how to manage these then?

Forgive me if I missed this, but will the related issues be listed under the page in question (e.g., as a backreference view)? I think it would be *critical* to know what issues are open relating to a Documentation page. If the link is a one-way path to posting new issues, it will become a black hole, leading to not only replication of issues but invisibility to end users as to open issues relating to the page.

If the issues are visible below the documentation page, then I would agree that this would be better than comments, losing none of the crowdsourcing flags while making transparent community concerns and questions re documentation.

Otherwise, even if "good" comments are only 5%, those good comments do help. The potential of the proposed approach to create a massive bottleneck to updated information is great, but I'll set that aside, assuming that aspect has already been considered by the Docs team.

laura s’s picture

To clarify:

d) Once we get #995292: Noderef field on issues for Documentation project, we would also put a block of Related Issues on the sidebar of each page (that's discussed on the other issue).

This is for a block on the Documentation node, or a block on the Docs issue node? If the latter (and I hope so), "related" is perhaps not clear enough. I would suggest something like: "Issues reported on this page", listing all open issues, plus the link to post a new. Whether this lives in the sidebar or bottom under the content, I don't know.

dww’s picture

@laura s: Yes, #33.d is about a block that appears on documentation pages listing any open issues that point back to the page you're viewing. Presumably over at #995292: Noderef field on issues for Documentation project there will be a UI for when viewing an issue node you'll see (all) the documentation page(s) the issue is pointing to.

laura s’s picture

@laura s: Yes, #33.d is about a block that appears on documentation pages listing any open issues that point back to the page you're viewing. Presumably over at #995292: Noderef field on issues for Documentation project there will be a UI for when viewing an issue node you'll see (all) the documentation page(s) the issue is pointing to.

@dww thanks! My apologies for charging in without a clear understanding. This issue is not on the radar of webmasters, so it was something of a surprise to see it, and I think many will be surprised. But as designed, with the back reference, this could be awesome! The back reference is the critical UI component, imho; without it, I think the change should be held until it can be done all together.

My thanks to everyone who's put so much work into this!

arianek’s picture

really excited to see this in progress - thanks to everyone working on and reviewing the patch!

"next steps" i'm pretty ambivalent, but +1 unless i can think of something i like better (which i can't right now!)

jhodgdon’s picture

See also:
#1027608: Use forum to make Discussion tab/block for Book pages (just filed)
#995292: Noderef field on issues for Documentation project (previously referenced)

Also I finally got my dev snapshot up and running and I'm working on this now, may have a new patch shortly.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
6.02 KB

Here's a new patch. Attaching so I can test (other reviews welcome too). I'm trying to figure out the best dev workflow here...

jhodgdon’s picture

FileSize
5.84 KB

The update function regarding the blocks is not quite right in that patch (the comment part seems to have worked fine). Here's a new patch for the block turning on part.

jhodgdon’s picture

FileSize
5.84 KB

Whoops. That one has a typo (db_update_sql vs update_sql). And the wrong weight for the next steps block. Let's try again.

jhodgdon’s picture

FileSize
5.84 KB

Some more tweaking is needed -- the block wasn't quite right. New patch attached.

So, you can now check this out in my Sandbox:
http://jhodgdon.redesign.devdrupal.org/node/627222
would be one place to start.

I am still not quite sure about two things:
a) Do we want this to appear on the Documentation landing page? If not, what would be the best way to turn it off? Maybe hard-wiring the node ID, but I'm not sure that is a good idea. I can see if there is any other logic in the drupalorg module about that.
b) I'm not sure why it doesn't appear on pages like contribute/documentation -- actually, the copyright block isn't there either. Any ideas? That is true on d.o as well. Perhaps that needs a patch.

jhodgdon’s picture

For anyone who wants to test this -- things to look at on http://jhodgdon.redesign.devdrupal.org/node/627222 and similar pages:

1) Wording of the block, including title.
2) Placement of the block
3) Do the links work (I think they do)
4) Do we want to tweak the default issue being filed - arianek - what would help you most in the queue?
5) From #75 above: do we want this block to appear on the Documentation landing page or not?
6) Somewhat separate issue, but why are the copyright and this block not appearing on the Getting Involved section, and is that intentional/desired?

Suggestions welcome!

joachim’s picture

Missing full stop after "Edit the page if you're logged in, or file an issue"

I also think it's a little low down on the page, but I'm not sure what to do about that. Only thing I can think of is to put the "The Drupal handbook pages are © 2000-2011 ..." back in the footer so the NS block is short enough to go above the book navigation.

jhodgdon’s picture

FileSize
1.7 MB

Joachim: thanks - I'll add the "." in the next patch.

Those are two separate blocks - so we can put Next Steps at the top and leave the copyright info at the bottom of the right sidebar. That might be a good idea... Any other opinions on the merits of this idea?

Also, I realized that no one but me can probably try the File an Issue link (not logged in). So attached is a screen shot of what the issue looks like.

jhodgdon’s picture

FileSize
5.84 KB

Here's a new patch fixing the missing "." noted in #77 (also live on the site).

dww’s picture

All looks good to me, with the tiny cosmetic exception that hook_update_N() functions should just be doc'ed with the summary of what they do, not "Implements hook_update_N()" for their summary. If you want to re-roll for that, cool. Otherwise, I can just do it while committing.

Next question is if this is ready to be deployed, or if we want to wait for #995292: Noderef field on issues for Documentation project? Once I commit this to drupalorg, it's going to be deployed live fairly soon (it automatically gets imported into our bzr vendor branch, and will probably be merged and deployed with other changes in a few days at most). So, if this isn't ready, I'd rather just not commit to CVS yet. Thoughts?

Thanks,
-Derek

jhodgdon’s picture

Really on the doc? Normally the standard for all hooks was to use the one-liner "Implements whatever()" so that it would link to the hook doc page if it were on an API site. I don't know that I agree with omitting the link as a doc standard -- when/where was that discussed?

I do see that that is what D7 appears to be doing. If it is a standard, we should add that to http://drupal.org/node/1354 -- it's definitely not mentioned there.

That aside, my opinion is that we should deploy it as soon as at least Arianek has also confirmed that she thinks it is ready and likes the default issue OK. I'd also like to reach a consensus on:
- placement - Joachim suggested maybe it should be at the top?
- Do we want this block to appear on the Documentation landing page or not?
- Why are the copyright and this block not appearing on the Getting Involved section, and is that intentional/desired?

joachim’s picture

> - Do we want this block to appear on the Documentation landing page or not?

Probably not -- there won't be bugs to report on that one, and it already has the 'help us' block.

lisarex’s picture

Looking good! Although perhaps this block would be better directly under the doc node body itself, because:

a) If someone read to the bottom and didn't find the answer, the Next steps would be in the best place to help them (doubtful they'd automatically look to the sidebar)

b) the 'Next steps' are specific to that node (well, the link to create an issue), while the sidebar navigation and copyright info are more general.

Thoughts?

Bojhan’s picture

@lisarex Thanks for sharing those thoughts, because I feel the same. I think they visually have to little prominence if they are placed on the right - below the node body seems like the best direction, but will need some adjustment because it is far wider.

dww’s picture

Status: Needs review » Needs work

Therefore, sounds like at least the placement update function, and perhaps the UI itself, need work...

webchick’s picture

Small nit:

"Edit the page if you're logged in, or file an issue."

You can tell if I'm logged in. ;) So the logic should be something like:

global $user;
if ($user->uid) {
  $output .= t('<a href="/node/X/edit">Edit</a> the page directly if you can fix it yourself, or <a href="/node/add/whatever">file an issue</a> if it needs someone more experienced to take a look.');
}
else {
  $output .= t('If you <a href="/user/login">log in</a>, you can edit this page directly or file an issue about it to bring it to the documentation team's attention.');
}
webchick’s picture

Oh, and agreed that this should really go at the bottom of the page, rather than at the bottom of the sidebar. On http://jhodgdon.redesign.devdrupal.org/node/627222, the very URL jhodgdon mentioned in #76, I completely missed it.

dww’s picture

Re: #86: Yeah, good idea. And in the else case, you should set the destination for once they log in so they return to the page they were looking at.

jhodgdon’s picture

I like the idea of putting the block at the bottom of the page, **except** that we have lots of pages out there right now that have a zillion comments on them, and the block would be after all the comments. So I don't know if this is a good idea either. Obviously, we also have a lot of pages with very long book outlines, so I agree that the current placement isn't ideal.

So maybe we should go ahead and put it above the book navigation in the sidebar?

Other ideas I'm seeing from above:

a) #86/#88 - detect logged in vs. not logged in. I think if we do that, we also need to change the block caching to not cached (it's currently per-page I think).

b) Don't let this block appear on the Documentation landing page.

Thoughts?

jhodgdon’s picture

FYI - list of pages with comments, ordered by number of comments
There are 102 pages with at least 20 comments, 302 with at least 10 comments, and at this moment, 1974 with at least 1 comment.

So for the time being, I think putting this block below the comments is not all that wonderful.

dww’s picture

@jhodgdon: Couldn't we do some magic in hook_nodeapi('view') to inject the block between the body and the comments?

jhodgdon’s picture

Yeah, probably. I'll see what can be done. OK, plan:

a) #86/#88 - detect logged in vs. not logged in. I think if we do that, we also need to change the block caching to not cached (it's currently per-page I think).

b) Don't let this block appear on the Documentation landing page.

c) #91 - Put this block at bottom of node before comments

Any thoughts on:

d) Was it intentional that there no copyright block on the Contribute to Doc page (contribute/documention) and other pages in the Getting Involved section? Should this block appear there?

jhodgdon’s picture

RE #92 - d -- I see what is happening. The Getting Involved book is part of the "Community" section, so it is not part of the Documentation section, and isn't getting the Documentation blocks. I guess that is OK as it is?

jhodgdon’s picture

FileSize
6.32 KB

Here's a new patch. Not sure if it's ready for review yet, stand by while I try it out on my dev site.

jhodgdon’s picture

Status: Needs work » Needs review
FileSize
18.21 KB
23.54 KB
12.5 KB
6.31 KB

That was almost right. Here's a new patch, and some screen shots of the bottom of the page.

A page with book nav and comments:
http://jhodgdon.redesign.devdrupal.org/node/101092 while logged in
http://jhodgdon.redesign.devdrupal.org/node/101092 while not logged in

A page without comments:
http://jhodgdon.redesign.devdrupal.org/node/221881 (shown while logged in)

I also verified that if you are not logged in and follow the log in link, it does take you back to the page.

lisarex’s picture

jhodgson, liking this a lot. webchick, good catch in #86!

My only suggestion now with the text would be to make the edit link more obvious/clear by making that link "Edit this page":
<a href="/node/X/edit">Edit this page</a>

And for non-authenticated, say "edit this page" as well also.

Is the Next steps in the right place? It's separating the list of child pages from the 'add child' page link. Certainly not a showstopper though. It definitely belongs above the Comments, and this will be extra incentive for us to deal with those pesky things :D

Bojhan’s picture

@lisarex I think it should go under everything, above comments but under everything else.

Unless I have missed it, I am not sure why we put a documentation team link here. Isn't becoming part of documentation team often a phase you enter after you explored how to contribute a page, or several? Since we are exposing this to people of all knowledge levels, I am not sure if its applicable to many. At the end of the day, every extra line makes the other two lines a tad bit less standing out.

arianek’s picture

- For the issue that gets created, rather than "Documentation problem with node/xxx" --> "Issue re: [node title]" would be nice, so that looking through the queue one can skim the actual topics (node id's aren't very helpful)... (this is assuming the nid is shown in a field on the issue or queue view...) otherwise the default looks good.

- I like the placement you came to (between body and comments).

- I wonder if we should actually explicitly say something about comments no longer being accepted - it might be super confusing for people to see comments but no longer see how to add them.

- I think we could use some bolding on the text of the block - perhaps:

Need more help on this topic? Ask in the Forums or on IRC.
Does this page need corrections or updates? If you log in, you can edit the page or file an issue.
Want to contribute to documentation? Learn more about the Documentation team.

- Finally... regarding when to deploy this. I actually am *very* hesitant to deploy this without the block of referenced issues with it. I just think it will really ease the transition for people. Without that I think we are going to be in a bit of a world of hurt fielding WTF's from people... just my 2 cents. ;)

Thanks so much Jennifer for all the work on this patch, it's looking really great! :D

arianek’s picture

ps. re #96 from lisa +1 on the linking "edit this page" idea

jhodgdon’s picture

Status: Needs review » Postponed

If we aren't going to deploy this until the nodereference field for issues is deployed, then I will stop working on this for the time being, until
#995292: Noderef field on issues for Documentation project
and perhaps
#1027608: Use forum to make Discussion tab/block for Book pages
are fixed. I think that is going to be a while, since as far as I know we don't have CCK on the site at all yet.

When we get back to this issue, here's a list of what should be fixed relative to the patch in #95 [note that (b) is a proposal, needs review]:

a) Figure out how to get it below the "add child page" link. I think that will require switching from the nodeapi 'view' operation to the 'alter' operation. See node_view(), book_link(), and node_show() for why -- the Add Child Page link is in the 'links' section of the page, and the comments are added in right after that, so only the 'alter' operation would be able to add something between them.

b) Wording/emphasis change to:
Need more help on this topic or want to discuss it? Ask in the Forums or on IRC (comments are closed).
Does this page need corrections or updates? If you log in, you can edit this page or file an issue.
Want to contribute to documentation? Learn more about the Documentation Team that creates Drupal documentation.

For people logged in, the second line would be:
Does this page need corrections or updates? Edit this page or file an issue.

And re #97 - yes, I think we do want to have a link to join the doc team on every page.

c) Change the filed issue title to "Documentation problem with node/xxx" --> "Issue re: [node title]". This assumes the node ID is stored somewhere else in the issue, which requires #995292 to be fixed.

arianek’s picture

that all sounds good - and i think the noderef to book page is far more important than the one to forums for launching this change, but it would be nice to have both for the people using the forums to discuss things that may have ended up in comments before.

was it drumm who was working on putting cck on d.o? i thought someone mentioned that in dec...

laura s’s picture

Can't see the demo pages behind password access, btw.

webchick’s picture

The username/password is written on the password prompt. (drupal/drupal)

jhodgdon’s picture

RE #101 - I think if we can get the noderef for the issues working, the forums one will be 99% done, so we might as well do both.

jhodgdon’s picture

Why did this tag go away? adding it back.

jhodgdon’s picture

Uh oh. Tags have bugs! Adding back the tags that I assuredly didn't mean to remove.

jhodgdon’s picture

Another note: we may want this to apply only to Documentation pages, and may want something similar for non-documentation pages (not sure), but we should make sure that the links as proposed in #95 above only apply to pages in the Documentation section.

EDIT: As opposed to pages in http://drupal.org/about/drupal.org-FAQ etc., which are under the purview of the webmasters team, not the docs team.

jhodgdon’s picture

Added an issue summary. I guess I or someone else should also comb through here and see if there's anything that should be added to it (or to #995292: Noderef field on issues for Documentation project summary).

jhodgdon’s picture

Status: Postponed » Closed (won't fix)
nevets’s picture

Issue summary: View changes

Add issue summary