Proposal to open up editing rights

[Trevor Twining]

Addi,

I think you're right that it's a good time to bring this up again.

I'm not certain a large number of people will participate. That's not
necessarily a bad thing, though. Even if we just get *more* people
participating, then we're improving our reach and that's a success.

In any case, if there's a mechanism to keep an eye on the diffs, even if
it's just the Recent Updates then I can participate in watching the
queue as items come in. I'm sitting here at my desk anyway. :) I'm also
usually in IRC too, and we could use a little activity in there.

The community has grown a lot since the last time this was tried, so I
think it's a good time to give it another try. If it doesn't work out,
then maybe at the end we've recruited another couple team members.
That's not a bad outcome either.

TT

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)

So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.

Before I get to it, a bit of history:
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.

But there are some definite points to be looked at:
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.

Some issues we will need to look at:
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?

The idea is to try this out as a test. Here is my general plan. Help
me shore it up:
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.

So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.

Thanks
- Addi (add1sun)

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Joshua Brauer]

It's certainly worth giving it a try.

While editing the d.o module it might be good to look at adding some
verbiage about the style guide and anything else that would be helpful
in the node form for book pages. Whether or not the editing remains
open this would be handy for people creating new pages as well as
handy links for anyone editing the form. Perhaps even a handbook
editing pseudo block on the form (providing a little CSS can be added
to make it look sharp).

Josh

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Peck]

As I said in IRC, go ahead.

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Wolf Zirbs]

Hi Addi,
As a long time Member of D.O. and just a while joined the "Documentation
Team"
I want to give my 2 Cents:

1. Before allow full editing access to Handbooks, Member should get approved
by at list 2 "Senior" member
of "Documentation Team"

2. The new applying Member for "Documentation Team" should have a (to
establish) period of D.O. membership
and is not in a black list.

3. Add to "Documentation Team" the possibility to Edit also own posting for
review and or add good Posting
regarding good tech contribution to the Handbook

Thanks for this Andi.

Cheers

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (
http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Nathaniel Catchpole]

I think this is a good idea and hope it works.

There's a core issue (with working patch) for the disappearing edit
tabs/input formats weirdness here: http://drupal.org/node/91663 would be a
tiny patch to backport. I've seen module maintainers get confused because a
co-maintainer set a project node to full HTML for donate widgets, and they
thought they'd lost permissions to it, so this bug affects everyone.

Nat

[Michelle Cox]

Post by Wolf Zirbs
As a long time Member of D.O. and just a while joined the "Documentation
Team"
1. Before allow full editing access to Handbooks, Member should get
approved by at list 2 "Senior" member
of "Documentation Team"
2. The new applying Member for "Documentation Team" should have a (to
establish) period of D.O. membership
and is not in a black list.

Maybe I'm misunderstanding this, but that sounds like _more_ of a barrier to
edit rights than what we have now, which is basically: "I want to join the
doc team" "welcome aboard".

Michelle

[Wolf Zirbs]

In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.
My proposal for a selection of who have "Fully edit access" and who not
have does not limit the joining to the documentation team, but give the
"Documentation Team" the chance to build an effective cooperating group.

We all know that there are 100 and more People who are happy to collaborate
and furnish good documentation
but IMHO I see as a priority task also to supply to Drupal.org Handooks a
higher standard of usability of the contained information.

We all know that a basic control is the base of good organizative
management. I care about this even I care to
grant access to every one who want help out in document and report in
Handbook.

Drupal as grown in an impressionable manner functionality and also this give
to anyone more handling power
but we should take care also who is using this powerfull tools and
functions.

Better have Applyer that have a period of practice and then approved to a
more powerfull contribution level as have 1000 that just register ones and
later on do not collaborate actively.

This could also be a grater motivation for every one to get to be part of
this great Community.


;-)

Post by Michelle Cox

Post by Wolf Zirbs
As a long time Member of D.O. and just a while joined the "Documentation
Team"
1. Before allow full editing access to Handbooks, Member should get
approved by at list 2 "Senior" member
of "Documentation Team"
2. The new applying Member for "Documentation Team" should have a (to
establish) period of D.O. membership
and is not in a black list.

Maybe I'm misunderstanding this, but that sounds like _more_ of a barrier
to edit rights than what we have now, which is basically: "I want to join
the doc team" "welcome aboard".
Michelle
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Cathy Theys (Yes! Training and Education)]

1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -> welcome!)
-Cathy

Post by Wolf Zirbs
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Victor Kane]

I hear what Michelle is saying...

This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.

It's called a wiki.

On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).

On the other... a Drupal Wiki section!

Then the result can be voted by people's legs (i.e. concrete results)
and not our abstract speculation here.

Maybe the wiki will be a disaster... most aren't :)

Victor Kane
http://awebfactory.com.ar

On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -> welcome!)
-Cathy

Post by Wolf Zirbs
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

Uh, well opening up edit rights is pretty much the wiki concept.
Everyone can already create new pages right now. This proposal is to
let them edit it too. Beyond that, I hate the idea of wiki formats and
don't think that will be a big boost and most likely leads to more
confusion. I also think that the freelinking aspect that is often
associated with a wiki is bad for structured information. The
semantics or the terminology used doesn't matter, it's the use of the
thing. So what exactly do you mean by wiki that isn't what we are
proposing already?

Addi (add1sun)

Post by Victor Kane
I hear what Michelle is saying...
This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.
It's called a wiki.
On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).
On the other... a Drupal Wiki section!
Then the result can be voted by people's legs (i.e. concrete results)
and not our abstract speculation here.
Maybe the wiki will be a disaster... most aren't :)
Victor Kane
http://awebfactory.com.ar
On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected
information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -

Post by Cathy Theys (Yes! Training and Education)
welcome!)

-Cathy

Post by Cathy Theys (Yes! Training and Education)
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Victor Kane]

Well, I think personally that the freelinking aspect could be a big
boost, although it is not necessary to include it.

My main concept about wiki and crowdsourcing is that you can maintain
a "wiki" area where a given set of authorized users (could be any
registered user) can create and edit and link, and that the actual
usefulness is something that can be proven in time. You don't have to
draw up any complicated set of rules and procedures. The value comes
from the crowd actually doing it.

At the same time the more classic "Getting started" and generally
acknowledged high quality stuff like the theming overview can be set
apart in a more controlled area.

Just my two cents. Keep up the great work, documentation team!

Victor Kane

Post by Addison Berry
Uh, well opening up edit rights is pretty much the wiki concept.
Everyone can already create new pages right now. This proposal is to
let them edit it too. Beyond that, I hate the idea of wiki formats and
don't think that will be a big boost and most likely leads to more
confusion. I also think that the freelinking aspect that is often
associated with a wiki is bad for structured information. The
semantics or the terminology used doesn't matter, it's the use of the
thing. So what exactly do you mean by wiki that isn't what we are
proposing already?
Addi (add1sun)

Post by Victor Kane
I hear what Michelle is saying...
This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.
It's called a wiki.
On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).
On the other... a Drupal Wiki section!
Then the result can be voted by people's legs (i.e. concrete results)
and not our abstract speculation here.
Maybe the wiki will be a disaster... most aren't :)
Victor Kane
http://awebfactory.com.ar
On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected
information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -

Post by Cathy Theys (Yes! Training and Education)
welcome!)

-Cathy

Post by Cathy Theys (Yes! Training and Education)
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

We can agree to disagree on the freelinking. :-) As for the Getting
started guide, that will be restricted already in the current
proposal. The theme handbook could be too, but probably not wholesale.
Keep in mind that any page with images will not be editable by regular
users. So, that said, it sounds like what you want is what the current
proposal would achieve.

- Addi (add1sun)

Post by Victor Kane
Well, I think personally that the freelinking aspect could be a big
boost, although it is not necessary to include it.
My main concept about wiki and crowdsourcing is that you can maintain
a "wiki" area where a given set of authorized users (could be any
registered user) can create and edit and link, and that the actual
usefulness is something that can be proven in time. You don't have to
draw up any complicated set of rules and procedures. The value comes
from the crowd actually doing it.
At the same time the more classic "Getting started" and generally
acknowledged high quality stuff like the theming overview can be set
apart in a more controlled area.
Just my two cents. Keep up the great work, documentation team!
Victor Kane
On Sat, Aug 30, 2008 at 7:43 AM, Addison Berry

Post by Addison Berry
Uh, well opening up edit rights is pretty much the wiki concept.
Everyone can already create new pages right now. This proposal is to
let them edit it too. Beyond that, I hate the idea of wiki formats and
don't think that will be a big boost and most likely leads to more
confusion. I also think that the freelinking aspect that is often
associated with a wiki is bad for structured information. The
semantics or the terminology used doesn't matter, it's the use of the
thing. So what exactly do you mean by wiki that isn't what we are
proposing already?
Addi (add1sun)

Post by Victor Kane
I hear what Michelle is saying...
This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.
It's called a wiki.
On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).
On the other... a Drupal Wiki section!
Then the result can be voted by people's legs (i.e. concrete
results)
and not our abstract speculation here.
Maybe the wiki will be a disaster... most aren't :)
Victor Kane
http://awebfactory.com.ar
On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected
information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -

Post by Cathy Theys (Yes! Training and Education)
welcome!)

-Cathy

Post by Cathy Theys (Yes! Training and Education)
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Victor Kane]

Right, and I guess now that I've added my two cents, I had better
participate too! :)

Post by Addison Berry
We can agree to disagree on the freelinking. :-) As for the Getting
started guide, that will be restricted already in the current
proposal. The theme handbook could be too, but probably not wholesale.
Keep in mind that any page with images will not be editable by regular
users. So, that said, it sounds like what you want is what the current
proposal would achieve.
- Addi (add1sun)

Post by Victor Kane
Well, I think personally that the freelinking aspect could be a big
boost, although it is not necessary to include it.
My main concept about wiki and crowdsourcing is that you can maintain
a "wiki" area where a given set of authorized users (could be any
registered user) can create and edit and link, and that the actual
usefulness is something that can be proven in time. You don't have to
draw up any complicated set of rules and procedures. The value comes
from the crowd actually doing it.
At the same time the more classic "Getting started" and generally
acknowledged high quality stuff like the theming overview can be set
apart in a more controlled area.
Just my two cents. Keep up the great work, documentation team!
Victor Kane
On Sat, Aug 30, 2008 at 7:43 AM, Addison Berry

Post by Addison Berry
Uh, well opening up edit rights is pretty much the wiki concept.
Everyone can already create new pages right now. This proposal is to
let them edit it too. Beyond that, I hate the idea of wiki formats and
don't think that will be a big boost and most likely leads to more
confusion. I also think that the freelinking aspect that is often
associated with a wiki is bad for structured information. The
semantics or the terminology used doesn't matter, it's the use of the
thing. So what exactly do you mean by wiki that isn't what we are
proposing already?
Addi (add1sun)

Post by Victor Kane
I hear what Michelle is saying...
This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.
It's called a wiki.
On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).
On the other... a Drupal Wiki section!
Then the result can be voted by people's legs (i.e. concrete results)
and not our abstract speculation here.
Maybe the wiki will be a disaster... most aren't :)
Victor Kane
http://awebfactory.com.ar
On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected
information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -

Post by Cathy Theys (Yes! Training and Education)
welcome!)

-Cathy

Post by Cathy Theys (Yes! Training and Education)
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Mike Parisi]

I am sitting here looking at my PDD, the API doc, and Google like mad trying
to find examples on how to use the hook_form_alter(). One thing that WORKS
and that I have purposed in the past is the PHP.org type system where there
are comments to the API.

The problem with this PHP.org is that some comments are incorrect and have
to be corrected, no one has permissions to do this so the comments become
replies after replies after replies. Maybe we should just give everyone
permission to write and edit comments to the documentation. Even give them
the ability to edit other peoples comments. I know there is some
restriction to the API that prevents this so maybe we should just link each
API and Document to an open WIKI page.

Mike

--------------------------------------------------
From: "Addison Berry" <***@rocktreesky.com>
Sent: Saturday, August 30, 2008 8:44 AM
To: "A list for documentation writers" <***@drupal.org>
Subject: Re: [documentation] Proposal to open up editing rights

Post by Addison Berry
We can agree to disagree on the freelinking. :-) As for the Getting
started guide, that will be restricted already in the current
proposal. The theme handbook could be too, but probably not wholesale.
Keep in mind that any page with images will not be editable by regular
users. So, that said, it sounds like what you want is what the current
proposal would achieve.
- Addi (add1sun)

Post by Victor Kane
Well, I think personally that the freelinking aspect could be a big
boost, although it is not necessary to include it.
My main concept about wiki and crowdsourcing is that you can maintain
a "wiki" area where a given set of authorized users (could be any
registered user) can create and edit and link, and that the actual
usefulness is something that can be proven in time. You don't have to
draw up any complicated set of rules and procedures. The value comes
from the crowd actually doing it.
At the same time the more classic "Getting started" and generally
acknowledged high quality stuff like the theming overview can be set
apart in a more controlled area.
Just my two cents. Keep up the great work, documentation team!
Victor Kane
On Sat, Aug 30, 2008 at 7:43 AM, Addison Berry

Post by Addison Berry
Uh, well opening up edit rights is pretty much the wiki concept.
Everyone can already create new pages right now. This proposal is to
let them edit it too. Beyond that, I hate the idea of wiki formats and
don't think that will be a big boost and most likely leads to more
confusion. I also think that the freelinking aspect that is often
associated with a wiki is bad for structured information. The
semantics or the terminology used doesn't matter, it's the use of the
thing. So what exactly do you mean by wiki that isn't what we are
proposing already?
Addi (add1sun)

Post by Victor Kane
I hear what Michelle is saying...
This calls for an industry standard. I think there are traditional
tools for crowdsourcing documentation, which is a great idea.
It's called a wiki.
On the other hand, the existing documentation as docs can still stand,
which can be either open / closed according to the discussion of those
most active (meritocracy rights).
On the other... a Drupal Wiki section!
Then the result can be voted by people's legs (i.e. concrete
results)
and not our abstract speculation here.
Maybe the wiki will be a disaster... most aren't :)
Victor Kane
http://awebfactory.com.ar
On Fri, Aug 29, 2008 at 11:53 PM, Cathy Theys (Yes! Training and

Post by Cathy Theys (Yes! Training and Education)
1) what if *anyone* could submit a revision
2) (with a simple, simple cvs like change log/note
3) [provide example/check box like: fixed typo, corrected
information,
clarified wording, major update]),
4) but it had to be approved... by a member of the doc group.
5) and *anyone* could join the doc group (like it is now, request -

Post by Cathy Theys (Yes! Training and Education)
welcome!)

-Cathy

Post by Cathy Theys (Yes! Training and Education)
In consideration that we all have responsability to provide exact and easy
documentation it should also take care of a standard of quality and security
on who is going to cooperate.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Lee Hunter]

There are two features of Wikipedia that I sorely miss in the Drupal docs.

One is the existence of a "Talk" page on a separate tab with each
article. This is one of the best ways I've seen to gather comments and
suggestions. With only the "comments" feature enabled (the status
quo), you wind up with just a linear and sequential view of everything
everyone ever said about the article. With the Wikipedia style Talk
page, anyone could refactor and archive old conversations and you
could put more important stuff (like a "to do" list for the article)
at the top and important contributions to the dialog could be
highlighted and flagged.

The other thing I sorely miss from Wikipedia, is the ability to add
ad-hoc categories and sub-categories. The current information
architecture of the Drupal documentation (especially outside the
developer docs) is - and I'm struggling to be diplomatic here - just
horrible horrible horrible horrible. And it seems that gaining
consensus for major structural fixes is difficult in this kind of open
source environment. However, if we could use categories like they do
in Wikipedia (it's actually a kind of hierarchical free tagging) you
wouldn't necessarily have to change the current information
architecture at all. The ability to apply multiple tags and to
organize them in a variety of hierarchies would provide incredibly
useful ways to navigate the information and it would allow people to
organically associate related content. The worst thing about the
current Drupal docs is the amount of related content that has been
split into meaningless silos. For example, if I'm trying to find
information about managing users, do I look in HowTos, Tutorials,
Snippets, Understanding Drupal, Videos and Slides, Getting Started,
Contributed Modules, Troubleshooting FAQ or all of the above? The
answer, of course, is "all of the above and a whole lot more". But if
we had some kind of tagging system, I'd only need to find one
administering user article and I'd be able to very easily see all the
rest just by clicking the "managing users" tag. It wouldn't matter
whether it was a contributed module, snippet, video, tutorial, how to,
troubleshooting and that's great because when I'm looking for
something I totally do not care in the least whether somebody else
considers it a howto, module, tutorial or tomato. As long as it
relates to my problem, that's what I want to see!

Lee Hunter
Technical Editor

Post by Mike Parisi
The problem with this PHP.org is that some comments are incorrect and have
to be corrected, no one has permissions to do this so the comments become
replies after replies after replies. Maybe we should just give everyone
permission to write and edit comments to the documentation. Even give them
the ability to edit other peoples comments. I know there is some
restriction to the API that prevents this so maybe we should just link each
API and Document to an open WIKI page.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Wolf Zirbs]

---> One big plus + to Talk system. IMHO is a very good base to start
over.Thanks
for the very reachfull feedback.
@wolfflow

Post by Lee Hunter
There are two features of Wikipedia that I sorely miss in the Drupal docs.
One is the existence of a "Talk" page on a separate tab with each
article. This is one of the best ways I've seen to gather comments and
suggestions. With only the "comments" feature enabled (the status
quo), you wind up with just a linear and sequential view of everything
everyone ever said about the article. With the Wikipedia style Talk
page, anyone could refactor and archive old conversations and you
could put more important stuff (like a "to do" list for the article)
at the top and important contributions to the dialog could be
highlighted and flagged.
The other thing I sorely miss from Wikipedia, is the ability to add
ad-hoc categories and sub-categories. The current information
architecture of the Drupal documentation (especially outside the
developer docs) is - and I'm struggling to be diplomatic here - just
horrible horrible horrible horrible. And it seems that gaining
consensus for major structural fixes is difficult in this kind of open
source environment. However, if we could use categories like they do
in Wikipedia (it's actually a kind of hierarchical free tagging) you
wouldn't necessarily have to change the current information
architecture at all. The ability to apply multiple tags and to
organize them in a variety of hierarchies would provide incredibly
useful ways to navigate the information and it would allow people to
organically associate related content. The worst thing about the
current Drupal docs is the amount of related content that has been
split into meaningless silos. For example, if I'm trying to find
information about managing users, do I look in HowTos, Tutorials,
Snippets, Understanding Drupal, Videos and Slides, Getting Started,
Contributed Modules, Troubleshooting FAQ or all of the above? The
answer, of course, is "all of the above and a whole lot more". But if
we had some kind of tagging system, I'd only need to find one
administering user article and I'd be able to very easily see all the
rest just by clicking the "managing users" tag. It wouldn't matter
whether it was a contributed module, snippet, video, tutorial, how to,
troubleshooting and that's great because when I'm looking for
something I totally do not care in the least whether somebody else
considers it a howto, module, tutorial or tomato. As long as it
relates to my problem, that's what I want to see!
Lee Hunter
Technical Editor

Post by Mike Parisi
The problem with this PHP.org is that some comments are incorrect and

have

Post by Mike Parisi
to be corrected, no one has permissions to do this so the comments become
replies after replies after replies. Maybe we should just give everyone
permission to write and edit comments to the documentation. Even give

them

Post by Mike Parisi
the ability to edit other peoples comments. I know there is some
restriction to the API that prevents this so maybe we should just link

each

Post by Mike Parisi
API and Document to an open WIKI page.

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

Just a reminder to please give feedback to this thread by September 8.
We've had a lot of good discussion and ideas floating around in here.
On September 9, I'll summarize what we've got and we can figure out
next steps, if any right now.

- Addi (add1sun)

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Andrew Berry]

Post by Addison Berry
Just a reminder to please give feedback to this thread by September 8.

Sorry for using this thread, I just recently subscribed so I don't
have a copy of the older message.

I had two thoughts on this which could work together. First, how about
automatically adding module authors to the documentation permissions?
Those who have committed code in my mind at least are very unlikely to
vandalize pages.

The other thought would be to do a "time delay" for new accounts being
added to the documentation team. For example, if an account is active
at least once a month for six months, then automatically add the
permissions, and send an email with style information and a thank-you
for participating in d.org's community. Of course, this could always
be overridden by a formal doc team request.

One other thing - the revision log field should be made to be
required. This probably requires a custom module to hook into the
form, but would be very useful.

--Andrew

[Nathaniel Catchpole]

One other thing - the revision log field should be made to be required.
This probably requires a custom module to hook into the form, but would be
very useful.
--Andr

A big +1 to required revision logs. Would be a tiny patch to
drupalorg.module and would be a bit of extra piece of mind opening things
up.


Nat

[Emma Jane Hogbin]

The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of

+1 on moving forward with this plan (and especially with a limited time
to start).

I would like it if there was also some kind of rating system on the
pages. Something like:
- "This is so good we're calling it 'Official' and locking it."
- "This has been through loads of edits, vote to make it 'Official.'"
- "Brand new page, edit me and make me better."

Yes, it's more tedious than a straight Wiki-style set of pages. I think
it would help to let people voice their opinion without having to leave
a comment or edit the page. We ran into similar kinds of questions on
The Linux Documentation Project when I was active a few years ago. This
was the solution that was proposed at the time. Another idea was to have
the ability for new authors to "lock" their pages so that they could not
be community-edited (but could be edited by the core LDP team). I think
that's less relevant here though.

regards,
emma

[Addison Berry]

I wanted to summarize the discussion around the proposal to open
editing rights to all authenticated users. There were a lot of ideas
that came up (and not all are in this summary because they may have
veered off the target topic. Don't fear they are still being compiled,
just not on this topic. :-))

So, the proposal as originally put forth:

Open up general handbook page editing to authenticated users for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is.

There were two overall sentiments in reaction to the proposal. If I
can be broad for a moment, we basically had one reaction of "Yes,
let's give it a whirl." and a second reaction of "Maybe, if we can
"control" it somewhat."

I got the overall feeling that those who responded were generally in
favor of exploring it, though with some with hesitation. Here are some
ideas that were put forth in terms of people's reservations/ways to
make it a more successful run:

"a mechanism to keep an eye on the diffs"
We do have the Recent updates page at http://drupal.org/handbook/
updates and thanks to Moshe there is a patch to add a direct link to a
page's diff from that table (http://drupal.org/node/304667).

"adding some verbiage about the style guide and anything else that
would be helpful in the node form for book pages"
We can definitely add something using hook_form_alter or a theme
override. We would need to provide the patch for infra to apply, so
anyone willing to pop up and take that on, would be appreciated.

Related (in a hook_form_alter kind of way): Making revision logs
required. Again, we should be able to add a simple validation rule to
the drupalorg.module. We just need someone with a little bit of time
to make a patch.

There was also a feeling from quite a few of wanting to have some sort
of "speed bumps" built in to the process. One suggestion was to have
even more restrictive access to the current doc team rights. Though I
got the feeling most did not agree with that direction. Some
suggestions put forth for regular authenticated users being
"moderated" or otherwise not directly given access were:
- revision moderation where edits could be made but the edits needed
to be approved by the doc team before going "live"
- "assigning each doc team member a manageable number of random
handbook pages to "adopt for life" and monitor for spam/vandalism."
the "owner (or owners?) would then be notified when chnages are made
to their pages.
- a "time delay" for new accounts. So that new auth users would have
to wait a certain period prior to gaining creat/edit rights.
We could also institute a rating/flagging system on the pages.
Something like:
- "This is so good we're calling it 'Official' and locking it."
- "This has been through loads of edits, vote to make it 'Official.'"
- "Brand new page, edit me and make me better."

Another suggestion for fast-tracking certain users, if speed bumps are
in place, is to "automatically add module authors to the documentation
permissions."

There are a lot of ideas here and the thing is we need to decide is if
instituting these restrictions is necessary in order to proceed. It
isn't just a matter of how we feel about open access, but all of these
"more restrictive" suggestions/enhancements will require signicificant
coding and working with infrastructure to get them into place. that
is, it won't happen any time soon and definitely won't happen with
some real elbow grease. These go well beyond a few lines of
hook_form_alter. The current infrastructure is not set up to do these
kinds of things. I'm not saying they can't happen ever, but simply
that they can't happen now and we would need to dedicate ourselves to
underlying grunt work to get any of these systems in place.

Regardless of "speed bumps" or not, we also touched upon the notion
(also in the original proposal) that there will be restricted access
to certain sections of the handbooks. The getting started guide is a
primary target for this, although the Them guide was also raised as a
candidate. I think this topic bears a touch of thought to have a clear
list of "restricted areas" before we open editing.

So, with all of that here is what I see as the next steps:
1) I think any way we go that the two modifications to the node edit
form suggested should be implemented. These two can be opened as
issues on the infra queue and patches need to be rolled:
--- Make revision logs mandatory.
--- Add additional "help text" on the book node add/edit screen.

2) We should also identify which areas of the handbook will be
considered "restricted" (e.g. the Getting started guide)

3) Decide if we wish to proceed without "speed bumps" for the one
month trial period or wait until we determine which to pursue AND get
them implemented on d.o.

My personal feeling is that we give it a try for the trial period and
if things seem too chaotic, close it up and then pursue the more
restrictive options. We can leave item #3 open for discussion the rest
of this week and make a final decision on Sunday, Sept. 14. Feel free
to argue back and forth all you want but also please give your clear
vote for or against the original proposal as it stands (open editing
to all auth users) before Sunday. We will tally responses from the
mail list and those present at the IRC meeting on Sunday for a final
decision by the team.


- Addi (add1sun)

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Larry Garfield]

Post by Addison Berry
I wanted to summarize the discussion around the proposal to open
editing rights to all authenticated users. There were a lot of ideas
that came up (and not all are in this summary because they may have
veered off the target topic. Don't fear they are still being compiled,
just not on this topic. :-))
Related (in a hook_form_alter kind of way): Making revision logs
required. Again, we should be able to add a simple validation rule to
the drupalorg.module. We just need someone with a little bit of time
to make a patch.

Even if we don't end up opening edit rights more widely, this is a good thing.
I keep forgetting to fill in revision info even when I should do so, so
having the system poke me about it would be appreciated. :-)

Post by Addison Berry
Regardless of "speed bumps" or not, we also touched upon the notion
(also in the original proposal) that there will be restricted access
to certain sections of the handbooks. The getting started guide is a
primary target for this, although the Them guide was also raised as a
candidate. I think this topic bears a touch of thought to have a clear
list of "restricted areas" before we open editing.

I'd mentally divide the handbooks into 3 general conceptual areas:

1) A person's first few days in Drupal.

2) Reference material for specific systems or modules. (Views API, D6 Menu
API, D6 theming guide, etc.)

3) Other.

#1 I'd say should be restricted. The "first impression" is something we want
to be very careful with, and I have no doubt the language there will be
heavily influenced by the redesign process. That should not be opened
globally.

#3 is, I think, the easy "yes" for opening up globally, if anything is.
That's the wiki-esque parts of the handbook, where wide-edit ability makes
sense.

#2 is up for debate. Ideally, those docs would be written by the people who
wrote that API and actively maintained by them, so we don't want just anyone
adding incorrect information. In practice, we know that doesn't always
happen so we may or may not want to allow anyone to tweak the menu API docs,
for instance. Perhaps those can either have a dedicated "owner" or be
public, case-by-case? (Eg, we have a "maintainer" for the theming API docs
so that's not open, but menu isn't be actively watched by chx and pwolanin so
that's open to all, as a possible example.)

[Andrew Berry]

Post by Larry Garfield

Post by Addison Berry
Related (in a hook_form_alter kind of way): Making revision logs
required. Again, we should be able to add a simple validation rule to
the drupalorg.module. We just need someone with a little bit of time
to make a patch.

Even if we don't end up opening edit rights more widely, this is a good thing.
I keep forgetting to fill in revision info even when I should do so, so
having the system poke me about it would be appreciated. :-)

Actually, this would probably be a good feature to add to the workflow
section in Drupal core. I know I have quite a few sites that could use
that feature. Making revision logs required would be a nice feature
for D7. I don't see an open issue for it, but doing it both ways
(through form_alter and a patch) should be pretty easy. If I can find
the time I'll take a look at it.

--Andrew

[Angela Byron]

Post by Andrew Berry

Post by Larry Garfield

Post by Addison Berry
Related (in a hook_form_alter kind of way): Making revision logs
required. Again, we should be able to add a simple validation rule to
the drupalorg.module. We just need someone with a little bit of time
to make a patch.

Even if we don't end up opening edit rights more widely, this is a good thing.
I keep forgetting to fill in revision info even when I should do so, so
having the system poke me about it would be appreciated. :-)

Actually, this would probably be a good feature to add to the workflow
section in Drupal core. I know I have quite a few sites that could use
that feature. Making revision logs required would be a nice feature for
D7. I don't see an open issue for it, but doing it both ways (through
form_alter and a patch) should be pretty easy. If I can find the time
I'll take a look at it.

Just a quick note that I would gladly accept such a patch into D7. :)

-Angie

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

Post by Angela Byron

Post by Andrew Berry

Post by Larry Garfield

Post by Addison Berry
Related (in a hook_form_alter kind of way): Making revision logs
required. Again, we should be able to add a simple validation rule to
the drupalorg.module. We just need someone with a little bit of time
to make a patch.

Even if we don't end up opening edit rights more widely, this is a good thing.
I keep forgetting to fill in revision info even when I should do so, so
having the system poke me about it would be appreciated. :-)

Actually, this would probably be a good feature to add to the
workflow
section in Drupal core. I know I have quite a few sites that could use
that feature. Making revision logs required would be a nice feature for
D7. I don't see an open issue for it, but doing it both ways (through
form_alter and a patch) should be pretty easy. If I can find the time
I'll take a look at it.

Just a quick note that I would gladly accept such a patch into D7. :)

There is now and issue with a patch for review to get this into core
for D7 (http://drupal.org/node/308352). I also created an issue to get
this modification onto d.o, since we won't be using 7 for a while. :-)

http://drupal.org/node/308675

- Addi (add1sun)

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Emma Jane Hogbin]

Post by Addison Berry
My personal feeling is that we give it a try for the trial period and
if things seem too chaotic, close it up and then pursue the more
restrictive options. We can leave item #3 open for discussion the rest

+1.

In my own words I think this means: allow d.o users to edit the
lowest-access pages and/or the lowest-context pages for the trial period
of one month. "Restrict" editing access to the high profile pages such
as the handbook (and theme guide) for now.

There are bells and whistles I'd like to see implemented, but I'd also
like to see how the masses deal with individual, contributed pages that
don't really fit "well" right now. Will they expand the content, will
they re-write the pages to make them better? Will they be inspired to
write new pages to fill in the blanks? WHO KNOWS! Let's give the
community the benefit of the doubt on the pages we think could use the
most TLC and see what kinds of awesome they come up with. :)

regards,
emma

[Steven Peck]

It's not 'lowest access' or 'lowest context' pages. It's all that do
not use Full HTML filter, which is most of them ( I think over a
thousand pages). We have better tools now then the last time this was
tried so it will be interesting to see the results.

On Wed, Sep 10, 2008 at 12:14 PM, Emma Jane Hogbin

Post by Emma Jane Hogbin

Post by Addison Berry
My personal feeling is that we give it a try for the trial period and
if things seem too chaotic, close it up and then pursue the more
restrictive options. We can leave item #3 open for discussion the rest

+1.
In my own words I think this means: allow d.o users to edit the
lowest-access pages and/or the lowest-context pages for the trial period
of one month. "Restrict" editing access to the high profile pages such
as the handbook (and theme guide) for now.
There are bells and whistles I'd like to see implemented, but I'd also
like to see how the masses deal with individual, contributed pages that
don't really fit "well" right now. Will they expand the content, will
they re-write the pages to make them better? Will they be inspired to
write new pages to fill in the blanks? WHO KNOWS! Let's give the
community the benefit of the doubt on the pages we think could use the
most TLC and see what kinds of awesome they come up with. :)
regards,
emma
--
Emma Jane Hogbin, B.Sc.
Founder, xtrinsic
phone: [phone]
web: www.xtrinsic.com
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Addison Berry]

Post by Addison Berry
There were two overall sentiments in reaction to the proposal. If I
can be broad for a moment, we basically had one reaction of "Yes,
let's give it a whirl." and a second reaction of "Maybe, if we can
"control" it somewhat."
There was also a feeling from quite a few of wanting to have some sort
of "speed bumps" built in to the process.
- a "time delay" for new accounts. So that new auth users would have
to wait a certain period prior to gaining creat/edit rights.

I think this one is a good idea generally for d.o, not just in the
context of editing pages that we are discussing here, but also for the
right to create new pages which everyone gets immediately right now. I
have created a webmasters' issue about it, if anyone is interested in
chiming in and/or helping: http://drupal.org/node/307650

- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Geoff Butterfield]

Good points all around. I'd like to mention one thing that might be
considered, as it certainly affected how I view participating in the
documentation process.

The issue is part version control and part... well, something else.
Here's what happened to me. I volunteered to start working on a
particular page. Without going into a lot of detail, this page was out
of date and somewhat confusing. I spent the better part of a weekend
carefully collating all the relevant data and crafting the shortest,
clearest, paragraphs I could, only to have someone come in a week
later and replace what I had written by copying and pasting some of
the older content from one of the pages that were defunct. It wasn't
just that my copy had been removed, or even edited for better clarity
or correctness, it was simply replaced by the older copy without
explanation. I doubt the person who has replaced the copy even
realized how much time and effort went into making the copy as clear
and concise as I could make it.

I wasn't mad about it, but it was frustrating. My feeling at this
point is that I'm unlikely to spend that kind of time working on
documentation without some kind of oversight. I just don't have the
time to burn.


Geoff Butterfield | Senior Technology Producer
The George Lucas Educational Foundation
Edutopia.org, Edutopia magazine, and Edutopia Video
p: 415-662-1741

Post by Trevor Twining
Addi,
I think you're right that it's a good time to bring this up again.
I'm not certain a large number of people will participate. That's not
necessarily a bad thing, though. Even if we just get *more* people
participating, then we're improving our reach and that's a success.
In any case, if there's a mechanism to keep an eye on the diffs, even if
it's just the Recent Updates then I can participate in watching the
queue as items come in. I'm sitting here at my desk anyway. :) I'm also
usually in IRC too, and we could use a little activity in there.
The community has grown a lot since the last time this was tried, so I
think it's a good time to give it another try. If it doesn't work out,
then maybe at the end we've recruited another couple team members.
That's not a bad outcome either.
TT

I'll start by apologizing for the long email here but I think this
deserves more than a few sentences. Also note that at the end I've got
a deadline for responses of Sept. 8. ;-)
So I have a proposal to put out to the team regarding opening up
editing rights to all authenticated users on d.o. This would be a big
change and I'd like us to really hammer this out in discussion so that
we identify and address pitfalls ahead of time as well as possible. I
have long been a proponent of absolutely *not* opening this up and I
still have concerns about it, but I'd like to see what the community
would really do with it. The Drupal community is very different now
than it was several years ago, whether it is different in a way that
would make open editing successful this time remains a question.
This has been done in the past and failed. Years ago all auth users
were allowed to edit the handbook and there was too much vandalism and
spam to be caught and cleaned up by the community. This is still a
concern and not one to be taken lightly.
* It requires MUCH less knowledge and time to fix a typo than it does
to author a new page. Same with rolling in comments, another common
task that the docs team is stretched a bit thin on.
* New users are the best poised to ferret out errors in
documentation,
but also the least likely to create new pages.
* While the barrier to joining the documentation team is low, it is a
barrier nonetheless, and one that is non-obvious to new users, whose
input we need the most. I've also found that many new people just
won't take the step to ask because they feel that it means they have a
certain time obligation that they don't feel they can "commit" to.
* We have a mix of input formats out there and anything above
Filtered
HTML needs to be restricted for security reasons. So even if we open
it up there will definitely be many pages that folks can't edit unless
they join the team, particularly pages with images. We can explain
this and make it clear what is going on but there will still be a lot
of folks that don't read wherever we happen to explain it and will
complain a lot. So we need to be ready for lots of forum posts/
issues/
irc pings about this unless someone has any other brilliant ideas
about it. ;-) We should have a standard explanation written up that we
can point people to and/or copy/paste into emails, etc.
* We are going to get vandalism, no doubt. So the trick is to see if
the community can actually self-maintain fairly well and keep up with
it. The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about
reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail. Any and all ideas about ways to help us track
what is happen and deal with it quickly are welcome. One thing that
comes to mind is that we do have a Recent updates page (http://drupal.org/handbook/updates
) and it would reduce a click if the table included a link directly to
the revisions tab of the page in question so you could easily review
the list, see the revision history and get a quick diff on changes.
This would require a patch to the d.o module so I'll write up a patch
for that either Sunday or next week.
* Any other issues we are missing here?
The idea is to try this out as a test. Here is my general plan. Help
Open up general handbook page editing to authenticated users (since
they can only edit Filtered HTML nodes, the Getting Started Guide and
other more "official" resources would be off-limits) for a trial
period of one month. Publicize what the deal is, and then assess the
number of reversions needed, and decide if we will continue or close
back up. We can extend the test a month at a time until we are sure of
our decision and just keep communicating with the community about what
the progress is. Basically, the community has asked for this and I
want to see if we can really handle it. If it works, awesome, if it
doesn't then this will give us some recent experience and data to
consider when the request is raised again.
So, let's talk about this on the mail list for a week or so and get
ourselves aligned about whether to agree to the proposal or not and
also hash out idea for how to actually deal with it. Please respond
with your thoughts to this list by September 8.
Thanks
- Addi (add1sun)
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Trevor Twining
http://www.trevortwining.com
http://civicactions.com/team/trevor_twining
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[c***@ronaldmulero.com]

How about assigning each doc team member a manageable number of random
handbook pages to "adopt for life" and monitor for spam/vandalism. They
wouldn't have to keep their adopted pages up-to-date or accurate, mind you,
they would just allow d.o. to automatically notify them any time one of
their adopted pages was edited, so that they could make sure the edits were
free of spam/vandalism. Karma would be awarded to doc team members with
consistently spam-free/vandalism-free pages.

Then, handbook editing could be opened up to any authentiated user.

Ron

...
The doc team in particular will need to make an extra effort to
keep an eye on things and be as responsive as possible about reverting
things and helping clean it up. this is the kicker and if this doesn't
happen, then this fail.
...

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/