A long time ago I got to spend a few years watching and learning from a man named Sherwin as he led a church choir. He was an absolute master in the realm of motivating volunteers. Here are some of the things I learned:
- Acknowledge contributions both explicitly and implicitly (Make sure you call out contributions, but also make sure that the very process acknowledges them.)
- Empower volunteers to do what they need to do without encumbering them with asking permission or seeking special dispensations.
- Provide adequate direction so volunteers can feel like they're moving in the right direction. Give them feedback about what they're doing.
- Set up clear milemarkers so that volunteers understand what is expected, rather than just saying "do whatever you think works". Sherwin did a marvelous thing with new choir members. With each new choir member, he handed a business card and said "If you ever can't come to rehearsal, please just give me a call and let me know." Did he need to know? Of course not. But the statement of "you're important enough in this place to let me know your status" was an incredibly powerful motivator.
Now, what are some ways we could improve in these areas in the docs world? Here are some suggestions.
- Make sure that handbook contributions are noted and obvious on handbook pages. (Created by jhodgdon on .... Last edited by arianek on ...)
- Aggregate handbook contributions (and contribution totals) in an easy to see place so that we know who's doing what.
- Create techniques to explicitly and deliberately acknowledge handbook editors
- Allow all volunteers who have been with the Drupal project 1 month (or who ask for the privilege) to have docs permission, with images and more significant HTML tags.
- Create d.o projects for managing sections of the handbook where overall collaboration and planning for those sections can be done, and interested people can get inspiration and direction. I proposed this more in depth in Project-izing Handbook Maintenance.
- Posting top handbook contributor lists regularly.
As I've said before, I think that Drupal contrib (and core) thrive because there's a clear way to contribute, and contributions are explicitly managed and acknowledged. Even though (especially core) can be really difficult to contribute to, a large cadre of people continue to do so both because it is possible to achieve what they want and because they get feedback from the community. We have to make that happen in the handbook.
One of my proposals for the planning session today: Figure out ways to publicly and explicitly acknowledge, direct, and motivate our fantastic volunteers.
Comments
Great stuff
Some great ideas here, and an even better overall sentiment. ;) Big +1 regardless of how we might end up tackling this.
I think the "Allow all volunteers who have been with the Drupal project 1 month (or who ask for the privilege) to have docs permission, with images and more significant HTML tags." is really important, and I hate denying Docs Admin perms to people simply because the Docs Input filter serves the dual purpose of "locking" community level pages. We really need to divide those two purposes so that anyone on the Docs team can access the tools they need to make their docs....um... "rock". ;)
A strong -1 for credits on doc pages.
For me personally, having my name plastered over the documentation would be a complete disincentive. Moreover I think it would make some kinds of editing work very difficult.
I would only ever feel comfortable with putting my name on something when it is my own words and quite often that just isn't the case with documentation. Many times I'm just copying and pasting text from here and there.
And then if I did write something original and my name was on it as the author I'd be pretty darn upset if somebody comes along and edits the piece in a way that I don't like and possibly makes me look foolish or illiterate.
Quite often documentation, especially editing, is about taking somebody else's words and restructuring and repurposing. Suppose an existing node is well written but is too long and should be broken down into a brief overview and two procedures (a very common scenario). If authors' names are automatically attached, what we wind up with is two new articles supposedly by me (although all I did was copy someone else's work) and the old article which is now just a couple of introductory sentences credited to an author who would be rightly dismayed to find that he has been credited for something trivial and I've been credited for his efforts.
I suppose we could ask people to manually fix the author's names but this just seems like another piece of needless drudgery that has nothing to do with the core task of doing good documentation.
I'm also generally opposed in principle to adding tangential information to the documentation pages. I think we have to respect the fact that the reader has come to the handbooks for the purpose of solving a specific problem. Probably he or she has already been barraged with a ton of unhelpful information and just wants to cut to the chase and get back to work. This is not the place for the tooting of horns and waving of flags. Anything that doesn't help the readers solve their problems should be eliminated.
Really the place to acknowledge contributions is on the user profile page.
Well said, Lee!
Thanks!
I'm not exactly pro
I'm not exactly pro page-specific credits, but I think it'd be nice to have some way to acknowledge and motivate the team a bit more. I think it was Lisa who mentioned they'd been tossing around the idea of badges for d.o (can't remember if this was actually in progress)? I think that would be a nice idea, user profile badges for people who've contributed docs. (Would be icing on the cake if it changed somehow for amount of contributions.)
I agree--well said Lee.
I agree--well said Lee. Arianek, I also like the general badge idea. There were a couple of other ideas the Neil mentioned too: one was a contributors list which could go so far as to weight contributors, so those of you putting in the endless hours get added credit. Another thought, was something of a character count so those contributing more would get more credit. While I have no doubt that people might chose to find some way around such a system to gain extra credits--I would also anticipate that there could be stiff consequences for violations of the community trust.
To help motivate people to contribute, it would be great to provide some clear path where meaningful hard work results in additional recognition and additional credit and I agree that badges would be a good first step. I'd love to see a badge solution that could be applied to other programs as well--rewarding contributors such as Presenters in the Drupal Dojo or Mentors in a Guild Program.
Another way to keep these contributions in check might be to develop a meaningful review and recommendation system, beyond comments, where respected members of the community are able to provide meaningful feedback and recommendations for individuals who have made meaningful contributions to the Drupal community. While we don't have a solution yet, we have been discussing something similar for Mentors in the Drupal Open Learning Initiative (DOLI).
Anyway, I love the badge idea and my suggestion would be to start with something simple for now and perhaps kick around some ideas related to reviews and ratings that might be more meaningful in the future.
I agree with most of what
I agree with most of what everyone has said and just want to add that a clearer idea of the what and how would be nice. It seems like I have to open a few windows to find what I need to be able to help, and by the time I've found what I need I've spent my wad of time.
I feel that welcoming, not necessarily acknowledging, in an ongoing way is the way to keep people coming back to help as well as motivated. It doesn't seem as if the que is being used for individual pages, and I think that would make things easier as well, or a maintained page like the module handbook.
I commented on the readme.txt, and everything was discussed and posted in one place, it made it easy to track read and comment. I also get confused because it seems like I'm suppose to add a page or change what I think could use some help, yet I'm not sure if that's true. Should it to be posted to the que 1st and then when the change actually happens?? I'm still unsure of when I should just make changes and when it needs to be discussed.
It says "All content is written and edited by volunteers, please contribute where you see a need. If you have a Drupal.org account, you can edit a handbook page by clicking the “Edit” at the top of the page. You can also add new pages by using the “add a child page” link at the bottom. For more information on helping with the documentation, see quick ways to improve documentation."
Yet I did some stuff it was rejected and then I was told to add it to the que for review. This isn't welcoming, it's confusing. I'm not saying every change should be approved, but the idea that what I did was removed wasn't a warm experience, after reading the above, if I felt something needed more explanation I should just fix it. Now I'm feeling unsure what is ok and what isn't. So for me #1 needs to be clarity on how this process is handled, and how a person steps into it.
Shari
I may be different,
may I never be indifferent.
Hi Shari - Thanks for the
Hi Shari -
Thanks for the feedback! I can totally see how it would have been confusing, when you are jumping in to help and then not sure what things are ok to edit, and what are things are more formal pages that have to be following a structure, etc. Sorry, I know I contributed to the frustration there! I sometimes can have a one-track mind when trying to get things done quickly...
I've been pondering what might help in this respect (aside from possibly putting the style guide in a more prominent place, though it still doesn't cover everything). Generally what we started talking about (at our docs team meeting in Vancouver a few weeks ago) is appointing some pages as "essential" documentation, which would be topics/pages that need more consensus (ie. discussing in the issue queue first before making changes) and/or stricter structures (ie. using a similar template/style for a set of pages that are similar, like the core module pages) are the pages that will be trickier to just have people jump in and help with. (Pages that are not part of the "essential" documentation, I think we can be far more flexible in this respect, and people can really freely edit them.)
These "essential" pages (we hadn't really decided how to refer to them yet - "core pages"?), might be only editable by docs admins (or a new role that is in between docs admin and a regular authenticated user), or might be watched more closely for changes by admins. And I'm not sure if we would tag them as "essential" pages, or use a different content type entirely, or...? But there is also the risk of making those pages and the people who can edit them seem more "elite" and we have to be careful about that as well. We really hadn't gotten too far into the conversation about this stuff, so there is a lot to figure out yet!
I was thinking in this case, maybe for pages where there are a bunch that are similar (such as the core module pages) that one of the team leads or docs admins take the time to draw up a template for the pages, so that there is an easy reference as to how the style and structure should go (beyond what is in the styleguide). Do you think that would help or just make it seem like more work to get familiar with what to do?
I'd be interested to hear any other ideas you have!
ps. Randy posted about this
ps. Randy posted about this "core"/"essential" docs idea here: http://groups.drupal.org/node/111884 if anyone wants to discuss it further.
A simple idea?
Maybe this would be a simple way to distinguish the "core" pages from the others. The instructions that Shari quoted are at the beginning of the documentation section. I would guess that the doc people who toil endless hours don't even really see those words anymore. But to a newbie like me, that sounds like anyone can edit anywhere. Perhaps something added to "core" where the copyright info is: "If you see something that needs changing here, please contribute it to the queue," with a link or further instructions.
Also, I agree wholeheartedly with Lee about author credits. Best not included on doc pages.
Nancy
Yep - this still depends on
Yep - this still depends on us refining the idea around 2 levels of docs, and how to manage that (in a technical sense)... so ideas around how to implement this would be helpful!
Potential for future employment as an incentive?
One motivation for volunteering in the Drupal community is to increase your potential for future employment. If you're an up and coming developer or themer, the opportunities are pretty clear and there are many ways to get noticed. For those looking to find their place in the Drupal economy as a technical writer, project manager, or customer/client adviser on the surface it doesn't look like there's much opportunity or a clear, obvious path to gain cred by volunteering.
I think more people would be motivated to volunteer time on Drupal documentation and/or attracted to the community if they saw a wider range of career paths and opportunities.
Gus Austin
Future employment?
That's a good point Gus and one reason I keep pushing the idea that we should be addressing the requirements of the much wider technical communication community, rather than just thinking about the needs of the Drupal docs.
Drupal currently has a few gaps that limit it's value as a general tech comm platform. If we fill those generic gaps (e.g. for single sourcing, variable text and integration with external tools), we'll see much wider uptake among technical communicators which in turn would mean that learning about Drupal and participating in the Drupal community would help people on that career path.
We're actually a little bit backwards in our approach. Rather than trying to get more Drupal people interested in doing docs, we would be much further ahead if we got more docs people interested in Drupal. The way to do that is to make Drupal work for their requirements.
In the short term...
In the short term I think just making it more obvious for those not very familiar with Drupal to 'Why they should get involved' would be a step in the direction. In doing a quick scan on drupal.org, I was a bit surprised not to find any info on the front page or primary landing pages. Also filed a related issue here - http://drupal.org/node/1010262
Improvements in tools/overall platform would seem to make good sense but a bit more resource/time intensive I assume.
Gus Austin
Add contrib module audits into the mix?
I've been thinking about this as well, and I'd love to see the process for peer review of contributed modules become a more recognized aspect of community contributions -
See http://groups.drupal.org/node/115554 for some initial thoughts here (and it's a wiki page, so feel free to add your own!).
FunnyMonkey
I don't know how much this
I don't know how much this really relates (aside from maybe getting docs team members to help with contrib module docs), but that said, I love this contrib audits initiative and hope that people take to it! ;)
I think trying to motivate
I think trying to motivate people to work on docs with the carrot of employment opportunities, is sort of barking up the wrong tree. For someone who becomes a very active contributor, I could see it leading to opportunities contributing to Drupal books, becoming a docs topic coordinator, or eventually (co)leading the Docs Team down the road... And if you got to the point where you were a lead or contributing to books, that would certainly get people in the community to know you, which would open up some doors job-wise. But I think it's a big stretch to say that should be a reason why people might work on docs.
The motivations in my view (and experience) are mainly: learning a lot about Drupal, sharing knowledge and helping educate other Drupallers, and getting experience writing/editing. (So generally people who like and are good at: learning, teaching, and writing/editing will be our target audience of potential Docs Team members). If it opens up job opportunities, that will be a byproduct, but it shouldn't be marketed as a given.
Right on...
I agree: learning, sharing, gaining experience -- those 3 are probably the primary reasons for most people who get involved in Open Source in general, with some variations.
So maybe one concrete thing we could do is make sure we get the point across in all of our communications of how Drupal doc work in particular satisfies in these three areas. I'm not sure we even have a "why" section on d.o/contribute/documentation. Maybe it should be the lead-in on that page? And we can also contemplate changing copy elsewhere on d.o where we draw people in (wherever that is).
Thoughts?
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Specific copy...
Right now http://drupal.org/contribute/documentation just says "Contributing to documentation is an excellent way to support the Drupal project, even if you are a beginner. ...." Rather bland.
How about if we replace the first paragraph with something more like:
Join the Drupal Documentation team!
Members of the Drupal Documentation team write the Drupal.org on-line documentation and the api.drupal.org programming API reference. Your can join the Documentation team, and in the process of writing and reviewing documentation, you will:
We especially welcome the contributions of Drupal beginners! In fact, beginners have a distinct advantage over the experts, because they can more easily spot the places where documentation is lacking.
The sections listed below will help you figure out what you can do to get started helping with documentation, [.... this is how the page continues now, and it seems fine to leave it as-is]
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
I think that looks great. :)
I think that looks great. :)
Excellent copy, +1 to this.
Excellent copy, +1 to this. And I think encouraging people with the prospect of employment is another good way to go. The amount of work available around Drupal is tremendous right now, getting any hands on experience with Drupal is going to help someone gain employment.
Drupal evangelist.
www.CoderintheRye.com
Themer != Dev;
Targeting doc audiences is great, and their respective incentives are important.
Employment is surely one powerful example of such an incentive.
Of the vast numbers of WordPress users,
MANY want to get to Drupal and simply do not know how. :-(
If we wish to discuss training for employment, then that is somewhat different from documentation.
There are corresponding docs and certification programs for PHP, MySQL and Linux.
These doc pages all follow similar formats, too cryptic for most.
I believe that Drupal.org should reference these LAMP documents more often.
Drupal, by combining and extending ALL of these technology platforms, is quite varied indeed.
Drupal serves many industries with great flexibility.
Drupal is heavily embedded in advertising and publishing.
I live in NYC and after watching for 3 years, I can say that "it has begun".
It is worth adding that the main industries that have really used Drupal are:
As with any online documentation, I wonder most how Drupal CMS technology might be optimized
to support materials that are both PROVEN EFFECTIVE as per their target audience
and MAINTAINED AS CURRENT.
Drupal Version 7 provides an opportunity to set new precedents in this regard.
The consummate skills of Drupal Themers (front end) and Devs/Integrators (mid/back)
are BOTH needed for a site of any real complexity.
I suggest that two corresponding certification tracks be proposed, where teamDev Drupal can easily allow for true expertise in an actual heterogenous production network environment.
The distinction between Themer and Developer skills/tasks is crucial.
With respect to both, Themers make dynamic pages. Developers build programs and applications.
Themers take things from memory and put them on the screen.
Developers put things in memory for the Themer to use.
Jack of All Trades, Master of None?
Meanwhile, many simply need to know: What is a CMS? Why Drupal? How do we get there?
Corp America needs skilled Drupal Staff with clearly defined expertise and tasks.
In Summary:
Targeting doc audiences and industries is great!
Their respective incentives are important. Cash is one.
Using existing LAMP doc bases, Themer and Dev Certifications
and focusing on teamDev industry problems and solutions would help!
Thank you all for this chance to articulate some NYC Drupal issues.
http://www.drupal.meetup.com/9
Jeremy Donson
Database and Systems Engineer
New York City
Make It Easier to Get Started
I know I still find the process of helping with documentation intimidating, which I presume others new to the project would as well. I felt a little better during the docs sprint at DrupalCon SF, because I had people to explain things while I was trying to help.
The basic instructions are "jump in and improve things." Where? How?
It would be much easier to get involved if there was a road map on getting started. Some links to the documentation standards, and then maybe an issue queue dedicated to small tasks that can be taken on. Success breeds success, once you have someone feeling like they are making contributions, it becomes easier to take on the next task.
Trying to improve...
It's sometimes hard for those of us who already understand the process to remember the intimidation factor, because we've obviously gotten past that. So your feedback is most welcome! I feel like I need more specifics, though, because we have certainly been trying to make it easier for people to get started. In particular, we have attempted to put together a bunch of pages under http://drupal.org/contribute/documentation that would help people find some specific tasks so they can get going on contributing to documentation.
So... have you looked there recently? If not, please do and offer some feedback on the current state of those pages.
And if you are speaking from recent experience, then maybe you could point to specifically which pages you checked out and what about them was still intimidating? That would be most helpful.
And if you didn't even know about http://drupal.org/contribute/documentation in the first place, let us know which pages you did end up on, so we can fix those links to point everyone to the section we are actually working on.
We're also working on adding a sidebar block to all doc pages with some more specific pointers, which is coming soon (hopefully in the next week if I can work up a patch).
Thanks!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
No I hadn't looked at the
No I hadn't looked at the new(?) pages. I was relating my experience from about 6 months ago.
The road map is there, as is the high level task list. I was about to say I didn't see style guidelines, but found them drilling down about 3 levels (is that too many???)
One thing I've been learning from my other life working in associations. Time constraints being what they are, breaking tasks down to "very" small chunks gets them done faster than asking for more general commitments. My personal experience seems to say an hours work is a good size chunk. So perhaps a good task/chunk would be to break the bigger priorities into lists of smaller tasks. So
with 28 comments in the issue is still a bit intimidating for someone looking for an evening's project to jump into...
Just my thoughts.
The link to the style guide
The link to the style guide was in the old docs block (that was in the sidebar before the redesign) - I am pretty sure we have a ticket in with the infra team to get that block back, so all in good time. ;)
About parceling stuff into smaller chunks - I have nothing against that approach, it can work well if there are people who team up on a certain larger issue. We would LOVE others to take the initiative and help in this respect. Jennifer and I do as much as we can, but there is a huge amount of work and issues each of us is managing... so yes, help with that would be great!
LAMP Stack = Drupal's Technology Stack....
Hello All,
The idea of slicing and sequencing the tasks is GREAT. Nice!
Trying to do it all is admirable, but likely unnecessary. ;-)
@Arianek:
L A M P is the acronym for the 4 layers of code
that form the software "basement"
beneath Drupal and many other CMS platforms.
Drupal Module Integrators and Devs
all know a LOT of PHP and at least SOME MySQL and some Linux.
I would like to see the technical base of fine documentation at php.net and
dev.mysql.com be explicitly leveraged to take that burden OFF of Drupal Dev docs.
That Open Source tribute should be explicit, especially to PHP.net !
Also, Drupal documentation makes VERY clear
the VAST difference between Themes and Modules.
Themers also NEED to learn SOME basic php,
and also need to be expert with many other tools: html, css, jquery.
They also need to learn the Drupal Theming API a little!
Developers need lots of PHP and MySQL and more!
Test-driven is not a nice idea, it is a necessity.
These two Expert Drupal Ninja roles complement each other,
as do Drupal modules and themes.
Drupal Docs should reflect this team approach,
and additional leveraged resources for
project management and network source code management just seem wise.
Feel free to inquire and disagree, as I learn more that way. Thanks!
Jeremy Donson
Database and Systems Engineer
New York City
@jdonson - sorry, i guess i
@jdonson - sorry, i guess i wasn't clear... i know what LAMP is, i just wasn't sure what that had to do with motivating volunteers. ;)
i'm still not sure i am understanding what your suggestion is - to have more general technical documentation on d.o? we've been trying hard not to duplicated docs for basic things like php, mysql, jquery, etc. on d.o and instead to point to their official docs...