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

[Bill Fitzgerald]

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