[documentation] [Documentation feature] Proposal: How to get more
people involved with documentation
pwolanin
drupal-docs at drupal.org
Sat Jun 17 02:03:11 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: pwolanin
Status: active
I very much like this proposal at the top by webchick:
"
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.
"
I think this would eliminate 99% of the possible "bad guys".
Obviously, this process would need to be explained clearly, but I think
would reduce the frustration level when encountering typos/broken links
(such as on http://drupal.org/node/326 where I noticed an issue to fix
the links on the queue many days ago).
pwolanin
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
------------------------------------------------------------------------
Tue, 06 Jun 2006 17:57:17 +0000 : zirafa
+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
------------------------------------------------------------------------
Tue, 06 Jun 2006 17:58:34 +0000 : Amazon
What page are you trying to replace? A page in the handbook or the help
text inside the Drupal software?
Kieran
------------------------------------------------------------------------
Tue, 06 Jun 2006 20:11:00 +0000 : O Govinda
Amazon wrote:
"What page are you trying to replace? A page in the handbook or the
help text inside the Drupal
software?"
If that's a question for me, I first of all had in mind the text at
/Home>>create content/ inside the Drupal software.
I also see ways to improve the "book module" help page in the handbook
(which nearly matches the help page inside the software).
Cordially,
O Govinda
www.jswami.info
------------------------------------------------------------------------
Fri, 16 Jun 2006 19:32:56 +0000 : rivena
There are 3 suggestions around for reducing barriers.
1. Create a separate domain for the handbook.
Plus is a great deal more flexibility over, well, everything. You
could even make it wiki-ish.
Minus, people will no longer be able to search it within Drupal itself.
*many* page links will be broken.
2. Increase the number of people with edit and create pages (without
moderation) permissions.
This could be done through clear instructions in the handbook.
Plus: People who took a little time to look for this info will easily
be able to get the right permissions.
Minus: No real minuses. :)
3. Let all registered users add pages to the handbook without
moderation, and edit their own pages.
Plus: very low barrier to entry, very transparent.
Minus: Crud will be created, and maintaining quality problems remain.
Those are the ideas, in a nutshell, I think. 2 is the easiest to
implement, 1 the hardest. Even if you do 1, you may still get the
problems of 3. None of these, by themselves, actually solve the long
term goal of getting a beautiful, easy to use, handbook.
Be brave and valiant, and, you know, pick one, already. ^.^
Anisa.
More information about the documentation
mailing list