Since add1sun's "Documentation is Hot" talk at DrupalConDC, I've been planning a flagging/rating system for our documentation on drupal.org. Some ideas:

1. A "This page was helpful" or "This page was not helpful" toggle for users so that we can find what documentation works and what doesn't. This could be using either flag.module, votingapi, vote up/down, etc.
2. If a user flags a doc page as not helpful, we could ask why. Was it confusing, was it outdated, etc. This way, users don't have to edit the docs page to set the 'page status' taxonomy element.
3. We can promote our "Most helpful" documentation pages and have a special page for reviewing our "least helpful" pages.
4. We crowd-sourcing the 'Page status' and don't need end-documentation-users to have to 'edit' a page to mark it as needs updating, opening the barrier for beginner users to help us with documentation.

Comments

leehunter’s picture

leehunter commented

Since the content is in a constant state of flux, I'm wondering if we might wind up with the ratings getting out of sync with the actual content. For example, imagine a page is rated as unhelpful but then someone fixes the main problem with the page - but doesn't change the rating. This could happen because the editor doesn't know why the page had a low rating in the first place and therefore doesn't know that it's actually ok now.

This could work the other way as well. The page is rated as helpful, but someone adds a pile of confusing stuff that makes it really unhelpful. The fact that the page is still rated as "helpful" will be quite confusing to everyone looking at the page. Eventually someone will mark it as "unhelpful", but I'm thinking that it might be quite confusing.

jweberg’s picture

jweberg commented

So maybe make the flagging or rating stay with the revision. In this way the revision edit gets a clean slate. Base the flagging on a percentage. That way low traffic pages get the same attention as high traffic pages. The only problem I see is that some documentation will be helpful for advanced users and not the beginners, and as such will get helpful flags even though it may not be THAT helpful. However, I say go for it. It's worth a try anyways. A few modules come to mind that might make this a little easier.

I think FIVESTAR would be a good module for this. It allows you to add a comment to your rating.

add1sun’s picture

add1sun commented
Status: Active » Closed (won't fix)

Overall, right now I'm -1 on ratings due the same concerns that Lee raises. Attaching a rating to a revision seems impractical since even minor edits would wipe out accumulated ratings. Going to close this as won't fix since there is no other support/activity around this.