This weekend in Seattle I met up with a few folks to talk about some larger documentation team issues which have come to light as a result of a tumultuous year for me personally, which caused me to withdraw from the community and my role as doc team lead. I realize that as the Drupal community has grown and changed, we have outgrown a model where one person alone can coordinate such a huge area as documentation. I asked several people, who had stepped in to fill leadership gaps and contacted me about general leadership concerns, to help me come up with a better plan for a sustainable doc team organization.
Based on various discussions over the last year, it seems that part of the solution involves improving the channels for communication and another part involves sharing leadership with as many people as possible. I feel that these changes will not only help us get docs back on track, but will make the documentation team stronger and more flexible as we head on down the road.
Communications
In the past, this group page (http://groups.drupal.org/documentation-team) was for announcements only. It's now open so that you can join, start discussions, and post events, and it will be the central clearinghouse for news and discussions about the documentation effort. This will make getting involved more discoverable and let us integrate our work with other groups in the Drupal community through cross-posting. Please note that this group only replaces the mailing list and not the documentation issue queue. The RSS feed for this group is http://groups.drupal.org/node/14492/feed
To avoid overlapping channels of communication, the documentation mailing list has been closed.
Roles and responsibilities
As the documentation has grown in size and complexity, more people are needed to coordinate and facilitate documentation activities. In addition to myself, who will continue as the overall documentation coordinator, the following people have volunteered to help with specific areas:
- Issue queue farmer and handbook content/editing coordinator: Ariane Khachatourians (arianek)
- Handbook structure coordinator: Lee Hunter (LeeHunter)
- API and core documentation coordinator: Jennifer Hodgdon (jhodgdon)
This information and a documentation team overview has been added to the handbook on the Documentation team page. There's still a need for more people to take on coordination roles, especially in various content areas. If you have a passion and/or expertise in a particular part of the documentation and you'd like to help make sure that it's current and complete, please contact me or one of the above coordinators directly.
The coordinators' role involves several activities:
- Identifying gaps and troubleshooting problems
- Acting as a resource for people with questions and concerns
- Helping new folks get up to speed and involved
It's important to note that the coordinator role is not a gatekeeper or taskmaster, it is a resource. As always, everyone is encouraged to jump in anywhere and any time you see an opportunity to improve the documentation. What's new is that we now have people who will make themselves available to provide feedback and guidance where needed.
Questions, comments or suggestions? Let's discuss it here!
Comments
This decision is evidence of tremendous bureaucracy
If only a minority wanted the documentation mailing list it should still remain open.
Who said God died and left you as Creator?
The mailing list was here way before you arrived on the scene.
You have no right whatsoever to close it.
Victor Kane
http://awebfactory.com
An important step forward
It's important not to make the dialogue divided into different places. Like Addi explained, moving to using the open group as our method of communication is really important for the continued viability of the docs team.
It will make our discussions more open and public so that new people can get familiar and involved more easily, and so that developers who aren't officially part of the docs team can communicate with us more easily. And it will let us integrate better when working on docs for specific projects, as we can then cross-post to those groups.
Ready to Help
Hi.
Bureaucracy is only bad if it impedes progress. Sounds like this is an widely-announced attempt to streamline progress on Drupal docs; let's all pull together to ensure that Drupal docs get done right.
For over 25 years I have created technical documentation for software. I will gladly help with Drupal docs in any way you can use my skillset. Writing, editing, or otherwise contributing to the Drupal docs will help me learn and provide benefit to the Drupal community.
Michael
Give love.
Great Michael!
That's great, we need the help!
There is some more general info about helping out here: [#700538] and if the high priority work for D7 is listed here: [#515870]
Ping one of us on IRC http://drupal.org/irc or drop a comment here if you need more guidance on where to get started!
I support add1sun
I support add1sun's decision to close the mailing list in favor of coordination on g.d.o and d.o. To me, it sounds like progress. Let's give it a try and see what happens. If it doesn't work, we can reopen the mailing list. Are you willing to give it a try, Victor?
Over organization is a bad thing in open source
The roots of open source is not herding cats, it's letting the cats attend to their needs in an open community.
The Drupal Dojo died through over over-organization and over-planning, that's a fact, when it was doing fine just by inviting the best minds in the Drupal Community to do a Sunday stint.
By shutting down the mailing list and concentrating here, the format may be "nicer" but fewer people are going to be involved.
I think some people are confused and think that the documentation itself is going to be here. Maybe that's because it changes so frequently no one knows where it is.
Anyway, sure, let's see what happens.
Of course I'm willing.
Victor Kane
http://awebfactory.com
Not fewer people — more!
Victor, I've been trying to help with documentation for over a year and a half, in part because I have a background in technical editing, which morphed into usability with an emphasis on accessibility, so I've seen a lot of places I could help. I have contributed a few edits here and there, but I could not figure out how to join the Docs team. I think I did send an e-mail somewhere, but this is the first obviously open door I've been able to find.
I can see from other responses here that I'm far from the only one in this position. Many more people, with a wide range of skillsets, are ready and willing to help — and thrilled to see this opportunity to participate.
I get an e-mail from every post to all the other groups I'm in, so the currency of the discussion should not be compromised. And I look forward to this opportunity to collaborate with you. I've read your book and respect highly what you have to offer.
Cliff
How come the group wasn't used for this before?
That's something I find it hard to understand, really. I am really glad that after so many months, you have found a door open to join the documentation team. Cool. But if wikipedia was created without having teams and meetings and planning sessions, what's wrong with jumping in and just editing the docs on d.o.? Those who are willing to help should have and should just jump in and edit the docs, on the basis of their own experience and fields of expertise. It would be great if we could have at least wikipedia level Drupal docs now, instead of all the ugly "DUPLICATE" and "ARCHIVE" notices pasted all over the place, things would be great.
But O.K., if people like to have meetings and overplan themselves, cool. But the mailing list wasn't the obstacle for the door to finding the documentation team, surely? Without arbitrarily "shutting down" (bravo winston!) the mailing list that is an important avenue for people to get a feel for what's going on, this group could have become active earlier, in exactly the way you describe.
I'll repeat: why do we have to buy in to false options all the time?
It wasn't the mailing list that has been an obstacle for docs being written up, surely?
Victor Kane
http://awebfactory.com
Writing Wikipedia and writing
Writing Wikipedia and writing Drupal docs are sadly not the same thing.
You might be interested in reading my blog post about this: http://www.drupaler.co.uk/blog/why-writing-drupal-documentation-harder-w... -- the brief summary is we lack a lot of the features of Wikipedia in our handbook pages.
It really was for me. I personally can't stand mailing lists and don't join them. I'm very glad to see the move to using a more flexible form of communication.
Visibility + Open = Participation
Thanks for the vote of support Dries. :-)
I really believe this step to a more open and visible docs team will do wonders for participation and helping people to self organize. Like Cliff, I had been working on docs here and there for a couple years already, and never really figured out how to "join the team" - I didn't join the mailing list until I started working on the D7 help page overhaul, and didn't even realize what its role is. I can only assume there are piles of others out there who were in the same boat.
I don't think anyone is confused about where the Docs will live. As always, they will be in Drupal itself, and then in the Handbook on d.o. This group is for discussing meta issues (so that they don't end up happening in the Docs issue queue - which was happening a LOT - because of people's reluctance or not even knowing about using the mailing list), and will allow anyone to easily organize and promote docs sprints.
And the fact of the matter is, there hasn't been that great of participation on the Docs team over the last 6-8 months. There have definitely been a committed core of people keeping things moving, but aside from the big D7 Help initiative, where a group of people really stepped up and helped out, which was wonderful, it has been really challenging to rally people. I think a large part of that was because of the group being closed, and having to rely on the mailing list (which I think was lacking a lot of the willing helpers), and things like Twitter to try and publicize.
Our hope is that this will not only bring our discussions into a more public venue and allow everyone more ownership and ability to take more initiative in the Docs world.
And I really can't emphasize enough the value of cross-posting to other groups, that will help immensely in getting developers and people who focus on specific areas of Drupal involved in writing and reviewing docs.
I can't wait to see how this plays out, as I am quite hopeful that it will empower those who want to help with docs immensely.
Re: "give it a try"
Give what a try? Coordination on g.d.o.? Absolutely!
Why does opening up the g.d.o. documentation group and using it as a place to organized synonymous with shutting down the documentation mailing list?
The argument seems to be that forcing one channel of communication is better. But as I've already mentioned both support and development have multiple channels of communication open and I don't see anyone saying shut down the dev or support mailing list.
What is stopping the documentation team from using gdo without shutting down the documentation mailing list?
Support and Dev Lists Should be Shut Down also
I'm thrilled with the fact that Docs has moved to g.d.o!
I really don't think it is about forcing one channel of communication. With g.d.o. you can have multiple threads going on at the same time. The efficiency part isn't about Doc team leaders have more control, but rather that they can address problems better and help people to collaborate together better when its easier to find and follow the existing conversations.
The only reason to keep a list serve is if there are people who only want to dialog via email and don't want to come to a forum. As Jennifer mentioned, with notifications and rss it's easy to read what is going on. The only thing groups doesn't have is the ability to post via email. Maybe after the re-design launches and things settle down, that functionality too will be added to g.d.o and even d.o.
I think the support and development list serves should shut down as well. Maybe we will end up being a model for those other lists.
Shai
Shai Gluskin
Content2zero
Sure, shut them all down
But until that happens I still see no reason why the documentation list qualifies for this "special" treatment.
Is it even worth mentioning that there was not one email sent to the documentation list suggesting that this was being considered other than the announcement two days ago that it was closed?
Apparently not, because the small group of people who seem to believe that they own documentation have decided by fiat for all.
Frankly, it is that mentality that has kept docs a backwater for so long imo.
Anyway, this will be my last post on this topic. It is too depressing for me.
Don't mean to depress you :)
@winston,
In November of 2008 there was a long discussion on this topic: you can find it here:
http://lists.drupal.org/pipermail/documentation/2008-November/thread.html
Because of the poor threading functionality of the list serve, you actually have to follow several threads in order to read the whole discussion.
Before I continue, let me inform you that I was not part of whatever circle of people decided to close the documentation list now.
That's really not fair. First off, Drupal is not a democracy, and there is no constitution which guarentees the kind of process you seem to expect. It's this actual lack of democracy, the fact that Dries can decide a lot by caveat or delegate that, is at the core of successful open source.
Obviously though, Drupal depends on contributions that are given voluntarily and if people weren't making a difference they wouldn't participate and we wouldn't have a project. So in this example, yah, on a process issue, Addi, ultimately a delegate of Dries or the Association, made a decision. Without decisions you can't move forward. But there isn't a hint of anything in this decision about shutting people out or curtailing people's voices or curtailing participation in Docs. Not at all! As Arianne pointed out, it actually makes the Docs process more transparent. You can think this was a bad decision, but to suggest it is somehow nefarious is ridiculous. And I'm sure it's a real drag for Addi to be thought of that way.
If you ask me, "Did Addi make a mistake in not giving greater advanced notice about this change?" I would say, yah, she should have given more notice. But that is small potatoes.
Ultimately this is about moving forward in a way that will include as many people as possible, and value their contributions and opinions.
Shai Gluskin
Content2zero
Not to mention
...and I have to bring this up - the list was not being used heavily at all. Maybe one message or two a month? Aside from when we were making the decisions on the D7 help, which all ended up as a discussion in the issue queue anyway because of the issues already mentioned, it has been pretty quiet for at least the last 6 months.
I don't see how this can impact anyone's ability to contribute in a negative way. Momentum on docs had really dipped anyway, and now we have a better tool at hand for those who have been putting a lot of time and energy into getting the ball rolling again, and getting more people involved.
To set the record straight
The fact that I think shutting down the docs list was wrong does not imply that I think the people who did this are bad people. I emphatically don't think they are bad people at all.
I reviewed my posts here. Where in my posts exactly did I suggest that this was done nefariously?
I don't appreciate being told that I suggested someone was acting nefariously or underhandedly when all I really did was register strong disagreement.
The only thing in my statements I can possibly see being construed that way was my use of the word fiat. I was using this in the definition of "an authoritative or arbitrary order".
Need Clarification on Authority from Dries
@winston and all,
I think the phrase that I found hostile, and so I responded strongly (maybe too strongly) is,
That insinuates people inappropriately assumed power. But I'm certainly open to another interpretation.
I think the issue is really about authority and how people respond to authority in an open source project.
The announcement of Addi's becoming "Docs team lead" came in a front page d.o. post by Dries Buytaert on October 10, 2008. From what I can tell, it is Dries' sole decision to "hire and fire" the person serving in that position. Not the Drupal Association nor any other group have authority to participate in that decision. It works exactly the same as how the core committer is chosen.
I think it is quite exciting and easy for people to talk about the incredible amount of collaboration that happens among thousands of contributors to make Drupal what it is.
But also part of the story is the fact that open source project leads have virtually exclusive authority to control the direction of those projects. Keeping that power in check is the fact that any group of people, at any time, can legally take the existing code-base, re-name it, and continue the project under a different leader.
Drupal has never forked, in part, because of Dries' wonderful leadership and the way he truly listens and desires people's input. (In addition, Drupal's modular structure allows for people who need more autonomy to be, essentially, their own project leads for the modules they contribute.) The Drupal project is really impressive in the breadth of people who have participated.
But what I would recommend Dries B. to do is be more explicit about the open source process and not shy away from explaining the role and authority of the project lead.
I also think the Drupal Association should do that as well. I could not find anywhere on The Drupal Association web site an explanation of the role of the project lead and what kinds of authorities he can delegate.
I think less ambiguity about how the process of Drupal actually works, especially vis-a-vis authority, would help people work better together and actually motivate volunteerism.
Shai Gluskin
Content2zero
some clarifications
Dries made the decision on my recommendation on a replacement for me. The person in the role then leads/owns the realm such as it is. Dries generally will not interfere unless there is abuse which has not happened in the past. In the years I was documentation lead I had one email from Dries on an issue and that was directing someone else to me to discuss it. How a given lead works is pretty much up to them.
Drupal has had forks. Only one public fork has survived and it has survived because it's a specialized version, but it is still a fork and it is used actively.
I strongly disagree with the manner in which the email list was closed. There is obviously a subset of people who enjoy forum only interaction and wax eloquently on it's supposed benefits. There are others who strongly prefer the email method. It is obvious that the proponents of email communications methods have been pretty much ignored in the discussion. That said, addi certainly does have the authority and responsibility to make such decisions as she chooses.
If the new team structure is going to foster a new openness, then this change merits a front page d.o. post. Because so many people won't know to look here.
Steven Peck
To sum up
@shai thanks for introducing the original thread, those of us who are new wouldn't necessarily have found it or known about it.
@all:
Sticking to the purely technical issues, this is how I believe it breaks down. Please correct me if I'm wrong, and add to these lists where you see fit.
Benefits of solely using groups.drupal.org:
Benefits of both mailing list and groups.drupal.org:
Looking back over the mail archive, I have to say, Groups feels a lot more browsable, the pictures are a nice visual cue about who is talking. A few people did note that groups could use some better functionality, such at the ability to respond by email.
The thread on the mailing list wasn't that long, there were several strong objections, but it seemed that the majority who responded then were for groups. Am I misinterpreting it?
Not Going to Do a Long Discussion On This With You, But:
And you wonder why people react negatively to your post? A transparent and widely announced attempt by the people charged with doing docs to get docs and the doc effort opened up, streamlined, and moving forward triggers this response from you?
Perhaps you don't have insight into how what you write comes across. But it sure seems to me an overreaction to a good faith effort by the appropriate people.
Please stick around and help; there's plenty of work for everyone.
Michael
PS Sorry: I attached this to the wrong note.
Give love.
Captain Nemo come up for air: it's the crowdsourcing Einstein!
@Captain Nemo You can disagree with winston, but lose the anti-democratic and smug "common sense majority" attitude. "Widely announced"??? The list was shut down without any discussion possible on that list. And what has stopped "the people charged with docs" (what the kind of language is that in an Open Source community??? docs never get done top-down). Look at the initiative taken by merlinofchaos for example, with the Advanced Help module and its splendid application to views, something applauded by the Doc team, which has archived a lot of snippets etc., but refers people to those docs? Also, parts of the documentation was improving significantly as module writers added stuff, except things are moved around all the time, so it gets frustrating (endless stream of "small wise group" making formal adjustments without opening up everything to crowdsourcing).
@Todd Nienkerk
I agree with winston: this same restrictive (no wiki approach, endless planning sessions getting nowhere, no good results for months/years) attitude aimed at a, yes, small group (because of the failure to leverage crowdsourcing)) approach has shown no good results, and it is this same restrictive approach that eschews crowdsourcing methods (what's a "doc lead" for chrissake??? what's it good for?) that have proven themselves effective all over the web, it is this same restrictive approach that petulantly and capriciously decides to shut down a mailing list without any open discussion on that list. That's the connection.
I'm so glad people are feeling happy in their new home here (again, why wasn't this initiative made before, shutting down the mailing list doesn't change the efficaciousness or not of this venue), but I doubt this top-down approach will help docs.
Victor Kane
http://awebfactory.com
Agree strongly with Victor
If you don't want to use the mailing list then don't respond to emails there.
Others who prefer working through email can still use it if they like.
I see no good reason to "shut it down".
Should we also shut down the dev and support mailing lists because we have issue queues and forums on d.o? It is exactly the same logic as far as I can see.
Who said God died
I think it was Friedrich Nietzsche
lol you rock
just for the record ;-)
+1
+1
Founder
http://www.larks.la
Robot Coordinator
http://droplabs.net
Organizer, Dragonslayer
http://drupal.la &n
I am interesting in helping
I am interesting in helping but at the moment I am maxed on capacity to actually volunteer directly for any tasks, however, I will keep an eye on the group though and chip in when I see the opportunity. I am interested in seeing documentation improve across the board.
Cool :)
Glad to hear there's a strong team in place. I hope to contribute to the docs team once the Drupal.org redesign project is out the door. We also found that without extra assigned roles, we'd never be able to keep the project moving forward.
==================================
http://about.me/lisarex
I think this is a great idea.
I think this is a great idea. I've been doing some documentation (screencasts, etc) and have wanted to get more involved, but found the mailing list format hard to follow.... so much easier when the whole thread of conversation is on site and nicely formatted.
Following threads...
... was one of the main reason we decided to switch completely over to g.d.o. You really can't search Mailman. And anyone who still wants to get email can easily set up notifications. Or they can use RSS. Or just visit the site. More options.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Delegation is good!
I'm glad to hear that people are getting official titles and responsibility, particularly in the areas of editing and structure. As you know from my frequent bleatings, I think those are more important than writing, and hope this change will help them get the attention they need. Onward!
Tom Geller * Oberlin * San Francisco * TomGeller.com
Author/Presenter, Drupal video series at lynda.com
Creator of materials for Drupal-focused companies
Tell me you're joking, please!
Hopefully you are using light humor...
Victor Kane
http://awebfactory.com
What's the drawback, really?
I hear a lot of people complaining about the mailing list being shut down, but I haven't heard a single argument illustrating how the mailing list is better than the group in any way. (The drawbacks to the list are outlined in detail by others above.) All that's at stake here is the channel of communication by which we organize — a mere tool to be used to make Drupal better.
It's pretty clear that what's upset people is that the list was shut down without a team-wide discussion. Nevermind the merits of the decision itself.
Todd Ross Nienkerk
Digital Strategist and Partner
Four Kitchens: Big ideas for the web
IRC: toddross
gmane and pan newsreader is a phantastic way to use mailing list
I am an ubuntu user and has just installed drupal 7
I find that pan newsreader is a phantastic way to follow mailing lists.
I am now following ubuntu user, kubuntu user and drupal support lists and checking them out several times a day, always seeing the latest posts in an very easy way - I find.
I have made a small minihowto about using pan:
http://minihowto.org/pan-minihowto.txt
I am 70 years old, and also the author of minihowto.org (a bit old) smile
My idea is that there is way too much documentation about drupal, spread out and mixing ver. 5, 7 and now also 7 - lots of videos with a person speaking english dialect very quickly and the screencast not very clear to see - very difficult for non native englsih speaking people as my self to understand.
I need at new minihowto about drupal 7 where everything is put together in the same place, only covering version 7, leaving all the other documentation as it is as a supplement.
But, that's is only my "dream" :-)