[documentation] [Documentation feature] Proposal: How to get more people involved with documentation

[Laura Scott]

What about just giving book edit permissions to a broad range of  
people who have expressed interest and initiative in helping in  
documentation? I don't see why it need be all or nothing, when it's  
really just a few dozen of us who are trying to make changes, even  
sporadically.

Laura

On Jun 6, 2006, at 6:43 PM, Jeremy Epstein wrote:

> The best solution, IMO, is to push to get http://drupal.org/node/48731
> ('save revision as draft feature') committed to core. Then, give all
> authenticated users the 'edit book pages' privilege. Users will be
> able to make any changes they want, and those changes will be saved as
> a new revision that goes into the moderation queue. In the meantime,
> the old revision is displayed to everyone (and the node cannot be
> edited by other auth users), until the change is approved.
>
> -1 to giving all auth users the 'edit book pages' privilege without
> this kind of functionality. The drupal.org handbook is not wikipedia:
> it DOES need careful moderation and monitoring, because it is a
> critical resource for thousands of site admins out there. Nobody wants
> to see our precious handbook get trashed, so let's not make any rash
> decisions about giving extensive privileges to all auth users.
>
> Cheers,
> Jaza.
>
> On 6/6/06, webchick <drupal-docs at drupal.org> wrote:
>> Issue status update for
>> http://drupal.org/node/67367
>> Post a follow up:
>> http://drupal.org/project/comments/add/67367
>>
>>  Project:      Documentation
>>  Version:      <none>
>>  Component:    Misc
>>  Category:     feature requests
>>  Priority:     normal
>>  Assigned to:  Anonymous
>>  Reported by:  webchick
>>  Updated by:   webchick
>>  Status:       active
>>
>> Djun Kim and I had coffee the other day and were kind of reminiscing
>> about the Vancouver documentation session and some of the items that
>> came out of that. Other people have mentioned before the "digg vs.
>> slashdot" factor, and I think we all generally agree that we need to
>> reduce barriers as much as possible for people to update  
>> documentation.
>>
>>
>> The system for the handbook we have now, quite frankly, kind of  
>> stinks.
>> While it's arguably harder for people to put spam/garbage in the
>> handbook (people can add pages about viagra willy-nilly but they're
>> placed in the moderation queue first), it also is harder for "normal,
>> do-gooder" people to submit/correct documentation. New pages can  
>> sit in
>> the moderation queue for days (or longer) before someone gets a  
>> chance
>> to approve them, module developers need to contact members of the  
>> site
>> admin team to update *their own documentation* in the handbook,  
>> and the
>> only way for Joe Random who discovers a typo in the text to fix it  
>> is to
>> create a documentation "bug" rather than just edit the text directly.
>> The concept of using "bugs" to track documentation problems is  
>> totally
>> counter-intuitive to people who have skills in writing and editing  
>> but
>> not coding (and some great writers fall into this category), and it
>> also turns what would be a "few seconds" fix into more like "few
>> minutes" fix which doesn't actually get fixed, but instead sits in a
>> queue until someone has a chance to take a look at it, hours or days
>> down the road.
>>
>>
>> In short, there are a lot of barriers in front of people who want to
>> help improve the handbook documentation, and removing those  
>> barriers is
>> necessary if we want the documentation to truly shine.
>>
>>
>> One idea is to move the handbook to a completely separate domain,  
>> such
>> as docs.drupal.org and point the Handbook link over there. We'd hand
>> 'administer nodes' privileges out to either everyone, or just
>> authenticated users. Site admins get "administer users" privileges  
>> and
>> can handle banning people who want to try and abuse these privileges.
>> This would also allow us to install additional modules such as  
>> Markdown
>> with SmartyPants [1] to make documentation editing easier, or Export
>> DXML [2] to allow other sites to pull the handbook pages for
>> themselves, without worrying about the performance/security(?)
>> implications for the main Drupal.org site. If I'm trusted enough (and
>> it is totally fine if I am not), *I would volunteer for putting this
>> together*.
>>
>>
>> If we want to keep everything at Drupal.org, that also works. We  
>> have a
>> new permission in 4.7 of "edit book pages" which is like "administer
>> nodes" except only for books. Just dole that out to all authenticated
>> users and bang, you're done.
>>
>>
>> "Edit book pages" permission to all authenticated users still too
>> risky? How about this? I code up a module or patch for book module  
>> (or
>> maybe actions/workflow could work for this??) so that upon creating a
>> new handbook page that gets moved out of moderation queue by a site
>> admin, you are added to a "documentation team" role that has "edit
>> book" privileges.
>>
>>
>> One way or the other though, we really need to fix this. Those are  
>> some
>> suggestions, anyone else have any others?
>>
>>
>> [1] http://drupal.org/node/9838
>> [2] http://drupal.org/node/39121
>>
>>
>>
>>
>> webchick
>>
>> --
>> Pending work: http://drupal.org/project/issues/documentation/
>> List archives: http://lists.drupal.org/pipermail/documentation/
>>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/