Proposal: How to get more people involved with documentation

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

+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.

+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

What page are you trying to replace? A page in the handbook or the help text inside the Drupal software?

Kieran

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.

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).

I created a "documentation maintainer" role on drupal.org. Steven Peck can assign people to this role, and such people will be able to edit the handbooks freely.

Hm... I tried editing a page, submitted, and it doesn't show up... Doesn't show up in the moderation que either. Am I supposed to wait? I seem to recall something annoying like that before...

And what about the moderation queue? Or is that outside of the doc maintainer purview?

Anisa.

According to this email I have been assigned the new role.
http://lists.drupal.org/pipermail/documentation/2006-June/004094.html

I have been experimenting with my new powers. However, things feel eerily the same! Examples of some things I aspire to do (starting with the most useful and working down):

1) I need to edit some pages but I can't: http://drupal.org/node/52743 (Full-HTML)

2) If I move a page, it goes into the moderation queue and I cannot process it. So it cannot be seen in the handbook until someone processes it.

3) I want/need to be able to delete some pages, eg.: http://drupal.org/node/50359 (ok, this is rare)

As far as I can tell, the only thing that has changed is I can now see an "Edit" sub-menu tab on some pages, however I could always edit (many of) these pages just by adding "/edit" to the end of the url.

There are two things I really want: Moderation Queue and Full-HTML editing. At least, I think the new role that has been created should have these things, with a screening process for candidates if that is necessary.

Thanks

"1) I need to edit some pages . . ."

It looks like the Full HTML input filter needs to be updated to allow documentation maintainers to access it before you'll be able to edit any pages which use Full HTML.

"2) If I move a page, it goes into the moderation queue . . ."

Right. The only additional permission offered by the documentation maintainers role is the ability to edit all book pages (that is, except for (1)). That does not include the moderation queue since that requires different administrative access.

"3) I want/need to be able to delete some pages"

See my reply to (2).

"There are two things I really want: Moderation Queue and Full-HTML editing."

At the very least, seems like to me like documentation maintainers would need Full HTML input format rights or otherwise many pages will be inaccessible to them.

At very least, it's rather meaningless if 'doc maintainers' are moderated. :)

Anisa.

Does drupal.org have any non-core modules installed that are involved in content moderation? If not, then I don't think there is a mechanism (other than the all-powerful admininster nodes permission) in the core modules to allow one user role to submit pages without moderation while requiring another user role to be moderated.

Just reporting back on my experiences.
The added filter is great. It is making life much much easier.

The moderation queue seems to be growing quite quickly. Unless I mis-counted, it grew by 20 over the course of a few days.

Maybe someone can tell me. What happens if there is a change pending in the queue, and then someone edits the live page? Do the changes get lost?

I don't think there *is* a live page if it's in the queue. I think that's a strong argument for giving more editors access to the moderation queue as well.

pwolanin
Ahh, you are right. I wonder, does that mean I can put the whole Handbook off-line if I edit a top level page? Eek! I don't think I'll experiment.

As discussed earlier, the only way to give more people access to moderation is to make them site admins. It's problematic to say the least.

how about a 'moderate nodes' permission?

the attached patch adds another permission to node.module. Allows those with permission to approve or unpublish nodes at the admin interface /admin/content

What about using nmoderation.module to assist in this? Doc contributors (but not regular users) can be given moderation access to vote up a page out of moderation into publication. Or use the queue module (although I understand that is being phased out). Drupal has ways to moderate content without admin access -- after all, that's one of the appeals of Drupal to community sites. Maybe it's time we added some more of our own dog food to the mix?

@webchick
Still trying to grapple with your "sad wink" smiley - disturbing! :-)

I'll certainly take you up on the "save as draft" link.

Question: If drupal.org uses 4.7.x and there is a feature freeze on 4.7, does that mean that features in drupal.org must also wait for 4.8?

in answer to my last question, to quote killes:
"there are a few minor hacks, but otherwise it is pretty stock 4.7."

Reverting this to a task to reflect open discussion.

The "moderate nodes" patch #18 is moved to here: http://drupal.org/node/71456

Trying to make this functionality available *now*, I rolled an entire separate module:

http://drupal.org/project/content_moderator

your review and feedback as to its possible use on Drupal.org would be appreciated.

Going by the description, this sounds like a fabulous module. Nice anticipation of avoiding going back into moderation and/or gaining access to restricted content.

Has anyone tested/reviewed my module? There seem to be lots of posts in the handbook moderation queue on drupal.org, and I'd like to think that this is a short-term solution for getting more people involved and more pages reviewed and approved.

this proposal might be a good way of getting more people involved:
Proposal: Drupal documentation wiki
http://drupal.org/node/105915

see also the forum post on the same topic:
Drupal wiki for documentation?
http://drupal.org/node/105706

some of the initial assumptions of this post are no longer valid as handbook pages no longer go into moderation.

Why not use the excellent userpoints module on Drupal.org? That way, members who have posted many times over a week or two would automatically gain the right to add/edit handbook pages. This would eliminate spam while making documentation more user friendly.

Heh, pretty much anyone can add/edit handbook pages. They just have to *want* to.

I'd just like to toss another two cents into the coinslot. Not everyone who wants to edit Handbook pages is good at getting complex technical ideas across in writing. If the Handbook system were open to all users, most users, or users with more than 20 forum posts, we'd have a mess. That's just the way of it.

I know firsthand that once the entire group of people is turned loose on a task, that task is never completed in a satisfactory way for use by the group. Case in point: I'm cleaning some databases for a 10-member sales team who can't even manage to format a US name, address, phone, and email the same way. And all of these people were trained by the same leader in the same office building!

Documentation writing requires some skill in verbal communication mixed with a newspaper editor's formatting skills. Toss in an intimate understanding of the topic you're writing about without actually being a coder yourself. We all know coders can't write documentation. Ever read a VCR instructional? :=)

What I'm saying is, those people with the skills and the drive to achieve are going to make it onto the team. Joining the Documentation Team is not hard. In fact, the more the merrier. As of March 2007, the Documentation Team has access to move, edit, reword, delete, or add to any Handbook page in the book, with the exception of the top-level pages. That's more than enough power to get the job done, I'd say.

Inviting the entire world to change anything at random is just never going to work like everyone hopes it will. That's all.

I would like to suggest the LIQUID WIKI ENGINE module for a Drupal native wiki implementation. The module also provides advanced access control to limit who can edit or delete. The wiki allows books to retain their heirarchy even when inserted into the wiki. (http://drupal.org/project/liquid) I would also suggest using a module like USER POINTS to automatically promote users to the Documentation Team role after a certain amount of content has been added by said user. (http://drupal.org/project/userpoints)

For a live demo of Liquid and User Points, go to http://www.kfol.org/ <== Yes, it shamelessly points to my own website.

Note: Whether a wiki or a book module, the functionality appears to be the same. Wiki provides a familar framework for some to use a standard markup language. However, I believe Revisions are handled by the core so I'm not sure there is much of a gain in funtionality by providing a wiki framework. I believe the gain is on a UI familiarity level.

Sorry to be harsh- but I think this is a bad idea. If a spammer adds 10 pages, he then gets to edit all pages on d.o before someone notices?

a group was created a while ago with edit books rights. this was assigned to the documentation team.