As of today, October 16 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 expands on that to allow editing of pages other than those you created. 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 to allow open editing. If the change causes too much spam or vandalism in the handbook, then we will be forced to revoke 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 attempted 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 Drupal.org handbooks 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 a lot of time, yet, the documentation team is small compared to the number of pages they maintain.
  • Make it easier for new users to make contributions: New users can potentially make the best contributions to clarifying and improving documentation, because they are painfully aware of problems. These users are also the least likely to know how to get access to editing rights.
  • 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 an understandable assumption.
  • 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!

Comments

lut4rp’s picture

With great power, comes great responsibility :-)

--
dum vivimus, vivamus
gpg: 9E656548
http://pratul.in

JohnForsythe’s picture

Wow, brave move. I think it's a good change, in theory. Hopefully in practice, too :)

Is there a recently edited pages list/feed somewhere? I'm sure I've seen it before.

Edit: found it.. http://drupal.org/handbook/updates

--
John Forsythe
Need reliable Drupal hosting?

coltrane’s picture

We need a feed of this information. Any chance of that?

add1sun’s picture

There is already an issue in the queue for that at #308354: Add a feed for recent updates to docs pages.

Lullabot loves you
--------------------------------------
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans

Drupalize.Me, The best Drupal training, available all the time, anywhere!

nehalmehta’s picture

This is really great move... This should strengthen drupal community... I hope this great move by drupal moderators is followed by audience in better style...
kudos to dare...
lets be responsible drupal geeks...

wonen’s picture

Yes, we have to beat other systems!

prbass’s picture

Great stuff - I think this is a really good move! Hopefully this will improve the quality of the handbooks.

Let's hope everyone can "play nice"!

-
http://prbass.net

bertboerland’s picture

a great move, good for getting more signups and I think the 'Lower barriers to participation" is the biggest pro. There are lots of users that are eager to help out on small typo's and sharing information, but just do not how. by lowering this entry point, we can get more people in our active group who can grow faster and better.

--
groets
bert boerland

--
groets
bert boerland

poggle’s picture

Good move in my opinion - not brave, more pragmatic.

I'm still a relative newbie (about a year or so) and would hope I may contribute at a lower level for others taking the same path as I.

I occasionally think that slightly adding to, or clarifying an existing statement or document is all that's needed to open the door in terms of broader understanding.

I'm happy to contribute within my ability :-)

davidlark’s picture

As a newcomer, you will follow the steps in the manual. Where they are incomplete or inaccurate, you will research the issue on the forums, and then update the manual. And all those who follow in your footsteps will thank you, even if they don't know your name.

Hip, Hip, Hooray!
Hip, Hip, Hooray!

xmacinfo’s picture

Thank you Addi for bringing this up this very day.

I've just enable the "Documentation team links" block in my account, so I'll be able to check from time to time the documentation updates.

And with it I just discovered a comment posted twice: "http://drupal.org/node/252619#comment-1062786". Obviously I cannot delete this, since it's a comment. But I'll keep my eyes open for book pages that I can update or fix.

catch’s picture

If you spot erroneous comments, or spam, or anything that needs fixing but which you don't have permissions to do, you can always file an issue at http://drupal.org/project/issues/documentation or http://drupal.org/project/issues/webmasters

Shai’s picture

Just to add to Catch...

It's possible you see something that is wrong... you may now have permission to fix, but you don't know how. Go to those same links Catch just posted and file an issue. The webmasters issue is better for spam reports while the documentation queue is better geared to handle content errors or things that just aren't coherent or organized poorly.

Go Docs on Drupal. Go Addi!

Shai

content2zero.com

abhigupta’s picture

While you are at it, can you please also install a Rich Text Editor such as YUI ... so that it becomes really easy to edit the handbook pages.

pyutaros’s picture

In the short term anyhow. However, and ideas for making the look and feel of Drupal.org different should be brought here: http://groups.drupal.org/drupalorg-redesign-plan-drupal-association.

Thanks,
Jonathan
Drupal's so easy, even I could do it.
http://www.idkd.net

davidlark’s picture

... until there's a core editor.

Meanwhile, contributors might try keeping a text file open with their favorite html tags so they can just copy & paste.

dnewkerk’s picture

It's not ideal, but until there's an editor (I'd love to be able to have something like BUEditor on drupal.org myself) I make use of this Firefox extension: BBCode (which can produce HTML tags around selected text, as well as custom defined tags such as <code>). There's also Text Formating Toolbar if you prefer, which I just discovered. You can enable a button on your toolbar to toggle it on and off as needed.

-- David
absolutecross.com
[new guide/lesson in progress: Creating a CCK and Views powered Drupal site - feedback welcome]

Chill35’s picture

I'd love to be able to have something like BUEditor on drupal.org myself

Me too, me too.

Chill35’s picture

Both extensions work in here.

They will work in handbooks too. For the Text Formatting Toolbar, one must access the HTML from the drop-down (on the far right of the bar).
This is bold. This is italic.

This is a quote. Uses the little guy with a speech balloon icon.

I just lost my edit cursor, though. It is simply invisible. FF3/Windows.

The first extension uses contextual mouse button.

Thanks again, David!

dman’s picture

A glorified tag inserter?

Hey, if you are keen on using a plugin, why not just use A full WYSIWYG?
... Now THAT is cool ... and I'm not a WYSIWYG fan ... I gotta try these out!

.dan.
if you are asking a question you think should be documented, please provide a link to the handbook where you think the answer should be found.
| http://www.coders.co.nz/ |

Chill35’s picture

Hi ex-coktail-shaker Thee-man :)

I am trying out the WriteArea plugin now. It uses FCKEditor.

I have not lost my cursor yet. Loaded with features (too much for my taste). Seems nice.

You have to give focus to your textarea, then right click and select Edit in Write Area. Then when you are done, you save.

I have gotten use to the BUEditor, what you call glorified Tag Inserter.

A list:

  1. I love Drupal.
  2. I also like Shopify.
  3. Easier to make a living with Shopify than Drupal.
  4. What to do.
  5. I prefer eggs with french toasts.

Caroline
11 heavens.com

rszrama’s picture

It's not like there are a whole lot documentation writers will need... if any. However, there's always that list of available tags right there on the page in the input format fieldset. Why keep a separate text editor open?

----------------------
Drupal by Wombats | Current Drupal project: http://www.ubercart.org

Chill35’s picture

Just to save time in typing tags and attributes on the page.

Even programmers dig time-savers like BUEditors or... Textile.

bq. A block of quote

click "here":http://example.com

Caroline
11 heavens.com

dman’s picture

If any web developer needs a cheatsheet open to help them do ultra-basic HTML - I don't want them writing documentation for me!

Tangentally related XKCD humor here

.dan.

Chill35’s picture

Me neither.

Caroline
11 heavens.com

juan_g’s picture

The similar case of Wikipedia is interesting but more difficult, because any non-logged in, anonymous visitor can edit Wikipedia pages. Because of this, they have quick undo links to revert changes (in the history section of each article). See their Cleaning up vandalism section.

Probably there will be much fewer problems with logged in Drupal users. ;-)

joetsuihk’s picture

look forward to a even stronger, more complete handbook

Joe Tsui's Blog

g089h515r806’s picture

can we add handbook page in other language,for example chinese, japanese,and so on.
many drupal developer does not use english as their native language, and the local community is always very small compared with drupal.org. If we can add other language hangbook page , i think there will be more people writting drupal articles.
------------------------------------------------------------------
zhupou,simple chinese drupal site

Chinese drupal tutorials Think in Drupal

Sree’s picture

Great move!

-- Sree --

-- Sree --
IRC Nick: sreeveturi

attila_fabian’s picture

I agree.
--
Fabio

Pasqualle’s picture

I am against using any other language than English on Drupal.org. If you write something in any other language it will be as disturbing as a spam.
You should use these sites http://drupal.org/language-specific-communities for support in other languages..

Pasqualle’s picture

http://chxcannotbedistracted.com/deleting-junk

it's funny, but it is absolutely true..

zzolo’s picture

This is awesome. I just simply love that we have a documentation team that is so involved and are making strides (positive or negative) to get more people to document more and grow the community. I am not a good Drupal documentor myself, but I really appreciate every bit of it. Good work!

--
zzolo

hass’s picture

This will open us to automated spam... couldn't we add a captcha or maths question to prevent this?

Boobaa’s picture

It should be much less irritating to normal users than evaluating expressions like lim_{0->x->\inf}{sin(x)*1/cos(x)} ;)

s.Daniel’s picture

Great thing but but we know that there will be the point where some spamhead will cause us much trouble. We need captchas at least for user register at some point.

Michelle’s picture

Why would opening up _editing_ cause a significant jump in the spam problem? I suspect most spam bots are programmed to add nodes/comments, which any authenticated user has been able to do for ages, rather than edit existing nodes. Not to say there won't be any edited in spam but I suspect it would come more from paid human spammers than the bots.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

acstewart’s picture

Brave move, I'm really excited to see what happens!

It probably would not exactly be out of the box, but one thought we had over here was to introduce a cliff of some time period of active participation before being able to edit handbook pages. This will keep the noise down and still allow users to be effective.. For those who want access sooner, they should be able to request it provided that their track record is in "good standing."

Just thinking out loud.. What do you guys think?

add1sun’s picture

This is already being discussed. :-) Feel free to jump in and help implement it. #307650: Delay edit/create perms for new users

Lullabot loves you
--------------------------------------
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans

Drupalize.Me, The best Drupal training, available all the time, anywhere!

Lynn Bankockor’s picture

Let me be the millionth person to say....AWESOME!!!

;D

whispero’s picture

Excellent.. Lets just hope trial goes well ;-)

Whispero

NikLP’s picture

dman’s picture

Not to bring all these happy people down, but...
What's the big deal? Everyone had always been able to add, contribute, clarify, or correct the handbooks by annotating them with notes.
It works fantastically for the php.net docs!

Was there some invisible barrier that was stopping people from adding more info? Is that barrier now gone and will they now start doing so just because they can now delete someone elses version?

Ah well, if every happy person here now goes and improves something for fun, that's a win I guess.

.dan.

mattie’s picture

imho:
- if I put a comment, will anyone read it except people searching the docs.. (i.e. not the maintainers ;))? possibly, but they are all volunteers right? and I don't see any sign of a comment feed. so how would they track them..? If you can do it yourself, you don't have to wonder about that
- I wouldn't create a comment just to mention a typo or something not that important
- when the page does get updated, will the comments get deleted?

just my 2ec

Michelle’s picture

#1: Yes. Handbook pages with comments are listed here and they monitored.

#2: Lots of people do, actually. I suppose it's moot, now, if we keep this new method, but leaving a comment to correct a typo is just fine.

#3: Yes. Comments are folded into the page and deleted as often as the volunteers can do it.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

mattie’s picture

wow, I'm impressed! I guess I seriously underestimated the power and professionalism of the drupal community.. :)

I guess I should have read the documentation of the documentation before starting to use it ;)

thanks for explaining

Shai’s picture

Though what Michelle wrote is all true --> I still think your experience and your initial conclusions are also true. Leaving a comment is simply not as motivating, fun, exciting -- whatever, then being able to fix something in real time. And I think the message of trust that the community delivers with this openness is really exciting.

I think this is a big change for the better.

Shai
content2zero.com

dman’s picture

if I put a comment, will anyone read it except people searching the docs..

... you mean : the very people who need to know the information you are adding?

I would have thought that's the target audience! ;-)

Anyway, for everyone who thinks it's so cool to be able to improve the docs yourself I expect to see you here soon Hello Mattie! :-B

.dan.

mattie’s picture

yeah, of course that's the audience :) but it's no fun if you post comments and you don't know if it will be incorporated in the page, also it gets kinda messy if everyone posts comments, so in the end no one reads them (of course, now I know the doc team dutifully cleans that up and even tracks comments :))

I expect to see you here soon

Dude, I made sure I first tried it out before placing a comment here ;)
now, please don't laugh at my 'silly' corrections ;)

okay, gotta go now, bye!

Pasqualle’s picture

mattie’s picture

it's funny, just last week, I was searching the documentation and thinking, ahh, if I could just update this, it would help future users having the same problem.. thanks! :)

it is a low barrier, but it is a barrier indeed! because one doesn't ask for an account just to correct a typo or add something very small

dman’s picture

I was referring to the ability to 'add comment', not ask for an account.
This has always been strongly encouraged - especially for corrections.

.dan.

mattie’s picture

Hi, sorry, I didn't read that page yet and I understand your reaction better now (so try to kind of ignore my other reply ;))

but I guess you can't expect everyone to read those pages. I for one just searched docs for what I needed them and quickly went on, I didn't search how I could try to contribute. I just thought, oh okay, I don't have edit rights, just forget about it.

mattie’s picture

btw, by asking for an account, I actually meant, asking for doc editing rights. I guess most people have an account, otherwise you can't post issues, forum messages, etc

yktdan’s picture

What changes do I have to make to D5 to impliment what you have implemented? I understand the perms, but clearly there are other things that have been changed.

Walt Daniels
Webmaster nynjtc.org

add1sun’s picture

All we did is add the edit book pages perm for authenticated users (and added the revert revisions perm for doc team). The preparatory work that we did was specific to a few extra things we wanted to do for drupal.org, but nothing that is particularly special:
1) we made the log message on book pages mandatory (hook_form_alter in the drupalorg.module)
2) we added a link to a page's diff to our Recent updates pages (that is a page generated by drupalorg.module so this was a patch to that)
3) set the input format to Documentation team format on pages we wanted to restrict access to

Lullabot loves you
--------------------------------------
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans

Drupalize.Me, The best Drupal training, available all the time, anywhere!

socialtalker’s picture

They are letting the inmates run amok! Rest assured I wont be participating, although I admit I cant wait to see how it will all look after the dust settles.

flash guy’s picture

maybe there will too much dust so it's never settle :(

davidlark’s picture

... so let's not assume that this will cause the end of the free world. I will be limiting my participation too, but wish the project well. My concern is that moderating the project & time spent on debates will drain energy from development. Of course it may invigorate it also. Will be an interesting episode.

I just pulled up three handbook pages, and they all appeared coherent. So four days of this policy has not caused WWIII.

vkr11’s picture

Shai’s picture

I know the experiment is going for a month... but there is so much interest here. Addi, I think it would be great if you gave a three-line interim report of how its going after the first week or two.

best,

Shai
content2zero.com

add1sun’s picture

Well so far, in my personal experience, it has been going really well. Most of the corrections/reversions I have seen (and not many of those really) were mainly due to people "testing" it out by just putting some nonsense in the page (like "can i really edit this?" or "sdfzsggsdfgdfg"). I haven't seen anything specifically "spammy" yet. By in large, I've seen many more useful fixes than junk.

For anyone that is interested, feel free to check in on the changes yourself on the Recent updates page and the doc team is currently scheduling an IRC meeting to talk about the trial. Everyone is free to help with the scheduling and attend the meeting to talk about the open editing experience.

Lullabot loves you
--------------------------------------
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans

Drupalize.Me, The best Drupal training, available all the time, anywhere!

Shai’s picture

rszrama’s picture

Was looking at the redesign mock-ups today and just realized why the thumbs up graphic has disturbed me... someone ate the hand's pointer finger. : (

----------------------
Drupal by Wombats | Current Drupal project: http://www.ubercart.org

JohnForsythe’s picture

Glad I'm not the only one who noticed that ;p

Still a marked improvement over this version... http://drupal.org/files/thumbs_up.jpg

--
John Forsythe
Drupal Modules - Find the module you need for your project!

add1sun’s picture

Talk to Senpai 'bout the images. ;-)

Lullabot loves you
--------------------------------------
Join us at Do It With Drupal!
A large scale, curated education event
December 10-12, New Orleans

Drupalize.Me, The best Drupal training, available all the time, anywhere!

rszrama’s picture

Oh my... I did something of a "cackle out loud" when I saw that picture. For some reason it just struck me as really funny. Staring at it a little longer it's almost like an upside down octopus popsicle. But I digress...

----------------------
Drupal by Wombats | Current Drupal project: http://www.ubercart.org

aufumy’s picture

I wonder what it would be like if there was this openness for contrib modules.

Waiting 2 weeks to see if a defunct administrator has really abandoned their module can be a little time consuming.

If a person wanted to add themselves as a developer for a contrib module, they could.

It sounds a bit crazy even to me, but I wonder what would happen in this scenario.

WorldFallz’s picture

but I wonder what would happen in this scenario

Serious maintainers would either 1) host their code some place besides drupal.org or 2) not post their modules at all. Neither of which seems very beneficial.

===
"Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime." - Lao Tzu
"God helps those who help themselves." - Ben Franklin
"Search is your best friend." - Worldfallz

_
Care about the future of the Drupal.org forums? Please join our conversation and show support for improving the forums infrastructure.

Michelle’s picture

That would be a disaster and I would be among those hosting my module on my own site where I didn't have random people committing changes.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

aufumy’s picture

That might likely happen, but another possibility might be, that only the people that have a clue would likely attempt to make changes to the code, and if they make incorrect changes, others in the know would overwrite their changes quickly.

I am just going under the assumption that it would follow a wikipedia style wiki'ocracy.

Michelle’s picture

There is a big difference between having someone make a change on a document page that has to be reverted and having anyone be able to commit to anyone's project. For the most part, there isn't much ownership of handbook pages. They are meant to be community written. Modules, on the other hand, are led by one or maybe a few people who have a plan for what the module is meant to accomplish and how it will be accomplished. Those people take on the responsibility of caring for the module and supporting it. Modules can be and frequently are passed on to new people when the old caretakers are no longer able to or interested in caring for it but it's a deliberate process. Having anyone who thinks they have a better idea be able to just jump in and start changing your module is a completely different thing and would alienate most if not all the maintainers.

Michelle

--------------------------------------
See my Drupal articles and tutorials or come check out life in the Coulee Region.

davidlark’s picture

Wikipedia seems to have a good deal of central control, a core group with privileges. They maintain a tight control, making sure the project stays true to concept. Module development probably benefits from a similar degree of enforcement; this could vary from project to project. If you wish to experiment by hosting an open CVS project somewhere, let us know how it turns out.

WorldFallz’s picture

I am just going under the assumption that it would follow a wikipedia style wiki'ocracy

It probably would-- but it sounds like you are assuming that's a Good Thing (tm) as it is with wikipedia.

As Michelle said, code != documentation. Whereas most people are able to write in the their given language, the same is not true of coding. It is a specialized skill that takes years of special training and/or experience to master. And even then, equally capable maintainers will have different opinions on module philosophy and architecture.

Besides, I have to think that if this approach was tenable, it would exist on a successful OS project somewhere.

===
"Give a man a fish and you feed him for a day. Teach a man to fish and you feed him for a lifetime." - Lao Tzu
"God helps those who help themselves." - Ben Franklin
"Search is your best friend." - Worldfallz

_
Care about the future of the Drupal.org forums? Please join our conversation and show support for improving the forums infrastructure.

aufumy’s picture

The Opensource community and reach is ever expanding.

Many would never have imagined wikipedia to be possible or successful or even as accurate as many other encyclopedias.

While Linux has been around for a while and helped to start the OpenSource revolution, I feel that communities such as Drupal have pushed the Openness barrier even further.

There is still a long way more to go.