[documentation] Proposal for handbook maintenance automation

[Steven Peck]

The handbooks are a wiki for people with appropriate rights.  There
are 98 of these people currently.  http://drupal.org/node/109372

current from: http://drupal.org/handbook/new-contributions
"In the past week, a total of 25 handbook pages were created. Of
those, 18 were spam. Of the 7 added, 5 were created by people not on
the documentation team:"

Before moderation was taken out, I did in fact open the handbook up to
editing to a wider role.  The moderation behavior was very annoying
but the simple fact is page vandalism was worse then the above
statistic.

I am not resistant to the idea of 'trusting the people', I have
experienced the reality of wide open edit access and the vandalism it
resulted in and frankly have no desire to repeat it.  It was a huge
time sink.

If companies are spending millions of dollars, then they can pay some
coders who understand FAPI to help with those documentation updates.
Frankly very few understand FAPI enough to write it clearly and most
of those do so from a developer point of view.  I certainly don't.

Versioning.  Versioning is hard.  Not the least because it can involve
duplication of content but because one persons contribution are often
not something that everyone has the interest in updating.  I don't
have access to cPanel nor am I interested in cPanel setup docs, but
someone contributed it for (say version 4.7).  So hopefully someone
who is interested will update it...  The volume of pages in the
handbook is staggering.

I'll have a seperate post on a path that I am pursuing.

-sp


On 8/8/07, Laura Scott <laura at pingv.com> wrote:
>
> On Aug 8, 2007, at 11:33 AM, Kieran Lal wrote:
> I think all the documentation should be a wiki.  Click here to edit.  Give
> admins the ability to lock pages, were necessary.
>
> The current status of having 50 comments on a page for something as critical
> how to upgrade your module to the next API version, is completely
> unacceptable.  We are forcing companies and admins to spend collectively
> millions of dollars on upgrading their sites between versions with
> inconsistent and unclear documentation.
>
> Agree on this 100%.
>
> Something sepeck and I discussed at OSCMS was that all the versions are
> intermingled, and that ideally we would have handbook views by version
> number, and done in a way that avoids massive node duplication in order to
> effect hierarchy.
>
> The handbooks are a particularly tough challenge. Wonder if what we really
> need are tabbed views for each page, with each tab offering potentially
> version-specific info. Even in a wiki, that approach might be helpful from a
> usability standpoint. The tagging alone gets us part of the way there.
>
> Laura
>
>
> --
> Pending work:
> http://drupal.org/project/issues/documentation/
> List archives:
> http://lists.drupal.org/pipermail/documentation/
>