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

Tue Jun 6 17:57:18 UTC 2006

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:   zirafa
 Status:       active

+1 to what webchick says.  It should really be Wiki-wiki-wiki-wiki
style.  We open all docs to community editing and if someone messes
something up we just roll back to a previous revision.  Perhaps we
could log these events (I'm guessing revisions get logged anyway) so
that we could monitor if trolls are going around destroying docs pages
and boot them (to the moon).

Farsheed

zirafa

Previous comments:
------------------------------------------------------------------------

Mon, 05 Jun 2006 15:26:26 +0000 : webchick

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

------------------------------------------------------------------------

Mon, 05 Jun 2006 23:54:52 +0000 : sime

A quick newbie case study.

In the last couple of days I have contributed to Amazon's efforts to
improve the E-Commerce handbook pages. My main interest was to change
the parent/child relationship of the pages.

It was extremely difficult. Each alteration (like changing the parent
page) put the document in the moderation queue, and I could not "see"
the results of my actions. So after a few simple changes I was
completely lost. If I didn't have Amazon's support (processing some of
my changes) I would not have been able do anything effectively without
an essay-length ticket in the doc queue.

Also, any page with a table is also out-of-bounds (Full-HTML), and this
has also been frustrating. The only way to do this is to create my own
html and then post the file to the issues queue.  And what about the
inevitable minor change?

So, while the current process "works" (as witnessed by a lot of great
documentation), I agree with webchick that it is *counter-intuitive*
for writers and *obstructs* the natural writing process.

thanks, Simon

------------------------------------------------------------------------

Tue, 06 Jun 2006 03:36:21 +0000 : cel4145

+1 for opening up editing the handbook pages to all registered users.
IMHO, there is no evidence that this is "too risky." If it creates a
problem, we could always revert back to the current editing privilege
setup or seek another solution.

------------------------------------------------------------------------

Tue, 06 Jun 2006 17:26:25 +0000 : O Govinda

I  agree with webchick that the barriers to contributing are far too
high. 

Contributing is cumbersome, the "bugs" approach doesn't work for
editors, and so on. 

I have 35 years of experience in professional editing. Could I offer a
small contribution sometimes? Yes--if you make it easy for me.

At http://drupal.org/node/50464 (you can skip to the bottom of the
page) you can see a suggested rewrite I've done for one page of
documentation. I submitted this 15 weeks ago. No response. 

Poor rewrite? Submitted to the wrong place? Said too much before I got
to the point? No one cares? I really have no way to know. Do I feel
encouraged to contribute more? Well. . . . 

On another point--permissions. A possibly useful tool for assigning
access permissions, if we'd rather have something other than
"everyone," might be the Simple Access module:
http://drupal.org/project/simple_access.

Cordially,
O Govinda
www.jswami.info