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

[Jeremy Epstein]

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/
>