There has been a long discussion on the documentation team about opening up editing rights to handbook pages for all authenticated users. We weighed out the pluses and minuses and as a group agreed that it is worth giving it a try for a *one month* trial period.

The original discussion started here: http://lists.drupal.org/pipermail/documentation/2008-August/006191.html and has a summary here: http://lists.drupal.org/pipermail/documentation/2008-September/006248.html. There is agreement from not just significant members of the community (sepeck, webchick and myself) but also the docs team as a group. The team does realize that this will mean more work to monitor the handbook and we have two other issues that are designed to aid with that:
#308675: Require revision log entry on d.o handbooks
#304667: Add diff link to book updates page

So specifically what we are looking at is making the following changes:
- Add the "edit book pages" perm to authenticated user role
- Add the "revert revisions" perm to the doc team role

(I also want to point your attention to #307650: Delay edit/create perms for new users which I think is a very good idea as well, but not deemed required for us to move forward with the trial period.)

There is also a component in the Documentation project for Vandalism/Spam if folks find things that need attention.

I have sufficient rights to implement the change myself so, if the webmasters agree, I can put this into effect once the two related issues are implemented. We will also make an announcement to the larger community explaining what is happening and outline the caveats in place: that this is a trial period and that not *all* pages will be editable due to format limitations - particularly in important areas of the handbook like Getting Started.

The last bit I would like to do is remove people from the doc team role who have not made an edit to the handbooks in the last 6 months. (Killes ran some numbers for me a little while ago #287909: Stats query request.) There is no need for them to have elevated rights anymore if everyone can edit which was out main motivation to add people to the team to begin with. The doc team will hopefully take on more of an editing/curating/maintaining role and therefor we want people who are active and motivated to take on some extra responsibility. I would, obviously, need assistance from infra to remove old doc team roles once we get this rolling and I will open a separate issue for that later, as warranted.

CommentFileSizeAuthor
#5 openEditAnnounce.txt3.7 KBadd1sun

Comments

catch’s picture

catch
he/him
Primary language English
commented

I already commentd on the list, but I'm +1 to this. Peple can already post new book pages, which has the same spam risks, with much less of the benefits.

add1sun’s picture

add1sun commented
Project: Drupal.org site moderators » Documentation
Component: Content moderation » Other documentation issues
Category: feature » task
Status: Active » Needs review

OK, we are pretty much down to creating the FP announcement. Here is a first rough draft, please edit it up. Our target date is October 15. I'm moving this back to Docs team queue so we can get this spiffed and ready.
========================================================
As of today, October 15, everyone with a user account on Drupal.org is able to edit most handbook pages (details are noted below). In the past this has been permitted for only members of the documentation team (or site maintainers). All users can already create new pages in the handbooks so this is a simple expansion.

This new permission is currently set to last for only one month, on a trial basis. At the end of the period, on November 15, the Documentation team and site maintainers will assess if the trial has been successful and make a decision whether to continue with open edit rights. If the change causes too much spam or vandalism in the handbook, then we will be forced to revoke the open editing. If we are unsure, we may decide to extend the trial period in one month increments until we can firmly make a decision one way or the other.

We hope that this proves to be a big boost to improving the handbooks here on Drupal.org (other rah rah stuff).

Why the change?

It should be noted that this has been done in the past and failed. Years ago all users were allowed to edit the handbook and there was more vandalism and spam than could be caught and cleaned up by the community. This is still a concern and not one to be taken lightly.

The reason we are attempting this now stems from several thoughts:
* It requires much less time and knowledge to fix a typo, or even roll in information and fixes from comments, than it does to author a new page. These are the kinds of regular maintenance tasks that we never have enough hands to complete.
* New users in particular are the best poised to ferret out errors in documentation, but also the least likely to know how to get the rights needed to help out. The issue queue is a formidable place for many folks, especially new or non-coding users.
* While the barrier to joining the documentation team is low, it is a barrier nonetheless, and one that is non-obvious to many users. We've also found that many people won't take the step to ask because they feel that it means they have a certain time obligation that they don't feel they can "commit" to. (This isn't true - there is no obligation to time or amount of work, but it is an eaasy assumption to make.)
* The community has grown and changed since this was last attempted. It could be a great help to our handbooks and we'd like to see if what was a burden in the past can be a useful tool now.

Some notes about handbook pages

While many, many handbook pages will now happily display an Edit tab for everyone, there are quite a few that will not. There are several reasons for this and here is a quick rundown of where you will find you cannot edit a page:

* Pages that have images or tables in them (links to examples) need an input format with additional HTML in order to display properly. This elevated format is restricted to use by Documentation team and site maintainers due to security concerns.
* There are some pages that are considered central and particularly important. (Nicely say we want to protect them.) Most of these pages are listed on the Locked pages list (link).
* Regular page content types or forum posts that have been added to the book outline are not editable. These pages may only be edited by site maintainers. The open and documentation team editing rights extend only to "book" content type nodes.

If you would like to help with editing pages that require documentation team access, feel free to join! (link) (little blurb about docs team)

heather’s picture

heather commented

I gave it a whack... tried to make some of it shorter, more succinct... took out things like "non-obvious", and "ferret", etc- where it might make it difficult for non-native English speakers. Added the 2008, wasn't sure if you were making this a book page? because not having dates... you don't know when something is.

I didn't know which examples you want to link to.

.. not sure about what title you're giving it. Threw one in there:

Calling all Drupalers to the Handbook!

As of today, October 15 2008, everyone with a user account on Drupal.org is able to edit most handbook pages (details are noted below). All users can already create new pages in the handbooks so this is an expansion to editing rights. In the past this has been permitted only for members of the documentation team (or site maintainers).

This new permission is currently set to last for a trial period of one month. At the end of the period, on November 15 2008, the Documentation team and site maintainers will assess if the trial has been successful and make a decision whether to continue with open edit rights. If the change causes too much spam or vandalism in the handbook, then we will be forced to revoke the open editing. If we are unsure, we may decide to extend the trial period in one month increments until we can firmly make a decision one way or the other.

It should be noted that this has been done in the past and failed. Years ago all users were allowed to edit the handbook and there was more vandalism and spam than could be caught and cleaned up by the community. This is still a concern and not one to be taken lightly. Nevertheless, we hope that this proves to be a big boost to improving the handbooks here on Drupal.org

Why the change?

* Distribute the work: Regular maintenance tasks such as fixing typos don't take alot of time, yet, the documentation team is limited in size.
* Make it easier for new users to make contributions: New users can potentially make the best contributions to clarifying and improving documentation, though they may be the least likely to know how to gain access rights for editing.
* Lower barriers to participation: While the barrier to joining the documentation team is low, it is a barrier nonetheless. The joining process has led people to conclude (erroneously) that this signifies a time obligation that they don't feel they can "commit" to. This isn't true- there is no obligation to time or amount of work, but it is understandably misleading.
* Times have changed: The community has grown and changed since this was last attempted. It could be a great help to our handbooks and we'd like to see if what was a burden in the past can be a useful tool now.

Some notes about handbook pages

During this trial period, all users should see an "edit" tab under the title of most pages. However, there are some pages for which editing is locked. There are several reasons for locked pages:

* Pages that have images or tables in them (links to examples) need an input format with additional HTML in order to display properly. This elevated format is restricted to use by Documentation team and site maintainers due to security concerns.
* There are some pages that are considered central and particularly important, and we want to make sure to protect them during this period. Most of these pages are listed on the Locked pages list (link).
* Regular page content types or forum posts that have been added to the book outline are not editable. These pages may only be edited by site maintainers. The open and documentation team editing rights extend only to "book" content type nodes.

If you would like to help with editing pages that require documentation team access, feel free to join!
http://drupal.org/node/23367

Wolfflow’s picture

Wolfflow commented

+1 Looks good. Well done

some add:
1. I would prefer ordered and listed items (Ordered Tag <ol>) in paragraph, gives a bit more authoritative statement.

2. I know maybe have to make an issue but for now: I would really be happy if the Join Us will have clear alias as to apply further or later as a big and visible add to our FP.

add1sun’s picture

add1sun commented
StatusFileSize
new openEditAnnounce.txt3.7 KB

OK, here is another pass with links. I'm attaching a text file with the HTMl in it too.
========================================
As of today, October 15 2008, everyone with a user account on Drupal.org is able to edit most handbook pages (details are noted below). All users can already create new pages in the handbooks so this is an expansion to editing rights. In the past this has been permitted only for members of the documentation team or site maintainers.

This new permission is currently set to last for a trial period of one month. At the end of the period, on November 15 2008, the documentation team and site maintainers will assess if the trial has been successful and make a decision whether to continue with open edit rights. If the change causes too much spam or vandalism in the handbook, then we will be forced to revoke the open editing. If we are unsure, we may decide to extend the trial period in one month increments until we can firmly make a decision one way or the other.

It should be noted that this has been done in the past and failed. Years ago all users were allowed to edit the handbook and there was more vandalism and spam than could be caught and cleaned up by the community. This is still a concern and not one to be taken lightly. Nevertheless, we hope that this proves to be a big boost to improving the handbooks here on Drupal.org and that the community will rise to the opportunity. The documentation team has been discussing and preparing for this since August and, much like the Getting Involved book, this has been a true community initiative.

Why the change?

  • Distribute the work: Regular maintenance tasks such as fixing typos don't take alot of time, yet, the documentation team is limited in size.
  • Make it easier for new users to make contributions: New users can potentially make the best contributions to clarifying and improving documentation, though they may be the least likely to know how to gain access rights for editing.
  • Lower barriers to participation: While the barrier to joining the documentation team is low, it is a barrier nonetheless. The joining process has led people to conclude (erroneously) that this signifies a time obligation that they don't feel they can "commit" to. This isn't true- there is no obligation to time or amount of work, but it is understandably misleading.
  • Times have changed: The community has grown and changed since this was last attempted. It could be a great help to our handbooks and we'd like to see if what was a burden in the past can be a useful tool now.

Some notes about handbook pages

During this trial period, all users will see an "edit" tab under the title of most pages. However, there are some pages for which editing is locked. There are several reasons for locked pages:

  • Pages that have images or tables in them need an input format with additional HTML in order to display properly. This elevated format is restricted to use by documentation team and site maintainers due to security concerns.
  • There are some pages that are considered central and particularly important, and we want to make sure to protect them during this period. Most of these pages are listed on the Locked pages list.
  • Regular page content types or forum posts that have been added to the book outline are not editable. These pages may only be edited by site maintainers. The open and documentation team editing rights extend only to "book" content type nodes.

If you would like to help with editing pages that require documentation team access, feel free to join!

add1sun’s picture

add1sun commented

ugh forgot to rebold the points under why and do the title. I can add those when I post tomorrow if no one else edits them in.

add1sun’s picture

add1sun commented
Status: Needs review » Reviewed & tested by the community

Just a note that I have created the unpublished forum post and am moving the announcement to tomorrow, October 16. Drupalcon just posted to the front page earlier today and I don't want to bump them.

add1sun’s picture

add1sun commented
Status: Reviewed & tested by the community » Fixed

OK, this is done: http://drupal.org/node/321601.

Anonymous’s picture

Anonymous (not verified) commented
Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.