[documentation] [Documentation feature] Proposal: How to get
more people involved with documentation
Bill Fitzgerald
bill at funnymonkey.com
Mon Jun 5 15:39:26 UTC 2006
One more thing --
If someone would give me the rights to edit handbook pages, and promote
pages from the moderation queue, I'd be glad to start digging in.
Thanks,
Bill
Bill Fitzgerald wrote:
> Huge +1 on this --
>
> I also think it could be even easier -- give the "edit book"
> privilege, and the ability to promote pages out of the moderation
> queue, to anyone who asks for it --
>
> This is a pretty low barrier to entry, but I'd argue that someone who
> couldn't figure out to ask probably shouldn't be writing documentation
> in the first place ;)
>
> /* ducks, puts on flameproof jacket
>
> FWIW, this is why I contribute more in the forums than to
> documentation -- responding to forum posts is faster and easier.
>
> Cheers,
>
> Bill
>
> webchick 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/
> ----
> Bill Fitzgerald
> http://www.funnymonkey.com
> Tools for Teachers
> 503 897 7160
>
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>
>
>
>
More information about the documentation
mailing list