[documentation] Proposal to open up editing rights

[Geoff Butterfield]

Good points all around. I'd like to mention one thing that might be  
considered, as it certainly affected how I view participating in the  
documentation process.

The issue is part version control and part... well, something else.  
Here's what happened to me. I volunteered to start working on a  
particular page. Without going into a lot of detail, this page was out  
of date and somewhat confusing. I spent the better part of a weekend  
carefully collating all the relevant data and crafting the shortest,  
clearest, paragraphs I could, only to have someone come in a week  
later and replace what I had written by copying and pasting some of  
the older content from one of the pages that were defunct. It wasn't  
just that my copy had been removed, or even edited for better clarity  
or correctness, it was simply replaced by the older copy without  
explanation. I doubt the person who has replaced the copy even  
realized how much time and effort went into making the copy as clear  
and concise as I could make it.

I wasn't mad about it, but it was frustrating. My feeling at this  
point is that I'm unlikely to spend that kind of time working on  
documentation without some kind of oversight. I just don't have the  
time to burn.


Geoff Butterfield | Senior Technology Producer
The George Lucas Educational Foundation
Edutopia.org, Edutopia magazine, and Edutopia Video
p: 415-662-1741




On Aug 29, 2008, at 7:06 AM, Trevor Twining wrote:

> Addi,
>
> I think you're right that it's a good time to bring this up again.
>
> I'm not certain a large number of people will participate. That's not
> necessarily a bad thing, though. Even if we just get *more* people
> participating, then we're improving our reach and that's a success.
>
> In any case, if there's a mechanism to keep an eye on the diffs,  
> even if
> it's just the Recent Updates then I can participate in watching the
> queue as items come in. I'm sitting here at my desk anyway. :) I'm  
> also
> usually in IRC too, and we could use a little activity in there.
>
> The community has grown a lot since the last time this was tried, so I
> think it's a good time to give it another try. If it doesn't work out,
> then maybe at the end we've recruited another couple team members.
> That's not a bad outcome either.
>
> TT
>
> Addison Berry wrote:
>> I'll start by apologizing for the long email here but I think this
>> deserves more than a few sentences. Also note that at the end I've  
>> got
>> a deadline for responses of Sept. 8. ;-)
>>
>> So I have a proposal to put out to the team regarding opening up
>> editing rights to all authenticated users on d.o. This would be a big
>> change and I'd like us to really hammer this out in discussion so  
>> that
>> we identify and address pitfalls ahead of time as well as possible. I
>> have long been a proponent of absolutely *not* opening this up and I
>> still have concerns about it, but I'd like to see what the community
>> would really do with it. The Drupal community is very different now
>> than it was several years ago, whether it is different in a way that
>> would make open editing successful this time remains a question.
>>
>> Before I get to it, a bit of history:
>> This has been done in the past and failed. Years ago all auth users
>> were allowed to edit the handbook and there was too much vandalism  
>> and
>> spam to be caught and cleaned up by the community. This is still a
>> concern and not one to be taken lightly.
>>
>> But there are some definite points to be looked at:
>> * It requires MUCH less knowledge and time to fix a typo than it does
>> to author a new page. Same with rolling in comments, another common
>> task that the docs team is stretched a bit thin on.
>> * New users are the best poised to ferret out errors in  
>> documentation,
>> but also the least likely to create new pages.
>> * While the barrier to joining the documentation team is low, it is a
>> barrier nonetheless, and one that is non-obvious to new users, whose
>> input we need the most. I've also found that many new people just
>> 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.
>>
>> Some issues we will need to look at:
>> * We have a mix of input formats out there and anything above  
>> Filtered
>> HTML needs to be restricted for security reasons. So even if we open
>> it up there will definitely be many pages that folks can't edit  
>> unless
>> they join the team, particularly pages with images. We can explain
>> this and make it clear what is going on but there will still be a lot
>> of folks that don't read wherever we happen to explain it and will
>> complain a lot. So we need to be ready for lots of forum posts/ 
>> issues/
>> irc pings about this unless someone has any other brilliant ideas
>> about it. ;-) We should have a standard explanation written up that  
>> we
>> can point people to and/or copy/paste into emails, etc.
>> * We are going to get vandalism, no doubt. So the trick is to see if
>> the community can actually self-maintain fairly well and keep up with
>> it. The doc team in particular will need to make an extra effort to
>> keep an eye on things and be as responsive as possible about  
>> reverting
>> things and helping clean it up. this is the kicker and if this  
>> doesn't
>> happen, then this fail. Any and all ideas about ways to help us track
>> what is happen and deal with it quickly are welcome. One thing that
>> comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
>> ) and it would reduce a click if the table included a link directly  
>> to
>> the revisions tab of the page in question so you could easily review
>> the list, see the revision history and get a quick diff on changes.
>> This would require a patch to the d.o module so I'll write up a patch
>> for that either Sunday or next week.
>> * Any other issues we are missing here?
>>
>> The idea is to try this out as a test. Here is my general plan. Help
>> me shore it up:
>> Open up general handbook page editing to authenticated users (since
>> they can only edit Filtered HTML nodes, the Getting Started Guide and
>> other more "official" resources would be off-limits) for a trial
>> period of one month. Publicize what the deal is, and then assess the
>> number of reversions needed, and decide if we will continue or close
>> back up. We can extend the test a month at a time until we are sure  
>> of
>> our decision and just keep communicating with the community about  
>> what
>> the progress is. Basically, the community has asked for this and I
>> want to see if we can really handle it. If it works, awesome, if it
>> doesn't then this will give us some recent experience and data to
>> consider when the request is raised again.
>>
>> So, let's talk about this on the mail list for a week or so and get
>> ourselves aligned about whether to agree to the proposal or not and
>> also hash out idea for how to actually deal with it. Please respond
>> with your thoughts to this list by September 8.
>>
>> Thanks
>> - Addi (add1sun)
>>
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>>
>
> -- 
> Trevor Twining
> http://www.trevortwining.com
> mail:trevortwining at gmail.com | skype:trevortwining
> http://civicactions.com/team/trevor_twining
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/