Documentation sprints for better docs and to grow the team

add1sun's picture

Edit, October 2 -- This proposal has been passed along to the Knight Foundation for consideration -- http://drupal.org/node/316402. End Edit

This proposal is to request funding to improve Drupal's documentation by conducting documentation-specific sprints. There are two major components to this project:
1) Tackle big Documentation team issues: Gather key people to work on specific documentation issues that will further the goals of the Documentation team, the handbooks on Drupal.org and documentation that ships with the Drupal code.
2) Grow the Documentation team: Conduct community sprints at Drupal group gatherings to grow the Documentation team and teach people how to contribute to documentation, including how to conduct their own sprints. Think of it as viral documentation love in addition to actually getting work done.

In conducting the documentation sprints at both DrupalCon Boston and DrupalCon Szeged, I've learned a few things that I think are very important. Firstly, having people int he same location working on the same goal can create incredible results in terms of work accomplished. Beyond that, the feeling of comradery and unification lingers long after the physical event. I've also found that many people who have attended the sprints have been interested in helping but were hesitant to jump in by themselves. Having a group of people there to personally walk them through the steps and answer questions real time lowers the barrier enough that not only do people finally engage but they also gain enough confidence to continue the work on their own once the sprint is over. Also, through leading these sprints I am beginning to get a much better sense of what is involved to create a successful sprint. Success being measured by the amount of work accomplished, as well as the number of new seeds planted for future growth.

Besides, the normal day-to-day monumental task of maintaining Drupal documentation, there are specific issues which can put the entire team into a holding pattern indefinitely. Some of these have to do with infrastructure and technical issues. Some simply have to do with having a larger goal defined and a sense of authority to enact it. Often, there is simply a lack of time and focus available for key people to sit down, figure things out and push them out the door. One very specific arena where this will be very important in the near future is the direction and implementation of the Drupal.org redesign as it applies to the Drupal.org handbooks. The handbooks are a major component of Drupal.org and making them easy to use for all levels of users is a high priority for the redesign.

In addition to the Drupal.org handbooks, we would also like to shore up and improve the documentation that ships with the Drupal code base so that users who do not have access to the handbooks online will still have a reasonable guide to get them up and running with Drupal. Finding the best way to implement a real change in this direction will require serious discussion with key people in various areas of the Drupal community.

The specific road map to address the two major goals of this proposal is as follows:

Invitation Sprints

Invitation sprints are very focused sprints of up to 8 people that are specifically invited for the task at hand. Each sprint would be two days long and the location would be determined by cities closest to the largest number of attendees and availability of space in a venue (e.g. a hotel meeting room or maybe donated space, if possible). There are two invitation sprints that would be the focus of this proposal:

Planning, road map, specs

This sprint would be the first one and would include key community members that have an interest in and experience with documentation. The focus would be to determine a prioritization of goals and a road map for how to achieve them, including specifications for code help, as needed. This would address both the Drupal.org handbooks and documentation included in Drupal's code base as well.

Code

Once needs are identified and we have specifications for what we want, we would have a code sprint where coders with the background and interest to help documentation can gather and actually produce the needed code. Doing this at a sprint allows focused time and immediate testing and feedback. The code produced could be for both core and contrib, depending on the needs identified and the best way to achieve them.

Community Sprints

Community sprints would involve organizing community documentation sprints during local DrupalCamps around the world. Since the camps will already be doing the organizational work and gathering large groups of attendees, there would be no overhead to running the sprints other than logistics to get there. These are designed to be very similar to the DrupalCon doc sprints by getting people to join the docs team and being focused on general documentation tasks. These would also teach people how to run their own local sprints at regular meetups and train people who would like to be regional sprint organizers.

I would attend the camp and arrange with the camp leaders to have a doc sprint track running for the entire camp (if feasible), which I would be responsible for running. My personal time would be donated and the funding requested would cover the logistical needs of travel, room and board. These would be spread out around the world and are dependent on locations that conduct DrupalCamps in the next year, so there are no specific locations determined yet. That said, I would like to conduct the following by region:

3 North American sprints
2 European sprints
1 Asia/Pacific sprint

In addition to physically going to large events I also want to organize a way for me to appear virtually at smaller events (local meetups, small camps) so that I can be a resource online for the organizers on the ground. This would not require funding in this proposal, but is added for completeness.

  • As a note about sprints at DrupalCons, I will still be doing that as well but I am not asking for funding for those in this proposal because I will not be focused solely on doc sprinting at Cons.

Sprint Documentation

A solid set of documentation (written and video) would be created to guide others in their own sprints; be they two people just meeting up to work on docs, to local meetups that want to have a sprint night, to running larger regional sprints at camps and conferences. The initial set of documentation and material would encompass not just information related to organizing sprints but also more generic info about the Documentation team, including policies and road maps, how to get involved, written and video instructions for tasks, etc. Everything written and created would be available in the Drupal.org handbook including materials like videos and PDFs.

One week (40 hours) of solid time would be invested in creating the documentation and materials early on, which would then be systematically refined in response to implementation at the sprints themselves. Another 40 hours spread over the following year would be spent on this refinement and creating additional materials.

How does your proposal meet the stated goals of the Knight Drupal Initiative program?: 

The number one priority of this proposal is to lower the barrier of entry to using Drupal for everyone through better documentation and easier access to it, both by making the Drupal.org handbooks easier to use and including more essential documentation with the Drupal core code from the start.

By also focusing on local events, I hope to encourage more local community work on areas that matter to them. As a vision for the future, once we have a more solid base, my next major initiative will involve getting local communities to work on translations.

How long will your project take to complete?: 

The initial phase of writing the initial documentation will take 40 hours and can happen within a month of the proposal being accepted. Organizing an international group of people for the Invitation sprints will vary, depending on the individuals' schedules but would ideally happen within the first one to two months. The Community sprints would be spread out within the next year, depending on when and where such events occur.

How will you implement and distribute your project?: 

I will organize the invitation sprints, attend the community sprints and write the documentation as outlined in the proposal. A specific list of individuals to attend the invitation sprints will be determined closer to conducting them.

All documentation that is written for this proposal will be available in the Drupal.org handbook. All work done at the sprints will be directly effecting the Drupal.org handbooks, or included in Drupal core or made available through contributed modules projects on Drupal.org.

What is your total budget estimate and how much funding are you requesting: 

The total amount requested is approx. $50,500

This is based mostly on estimates for travel expenses which can't be specifically known at this time. Here is a breakdown of the costs:

  • Documentation: 1 person for 80 hours at $50/hour = $4000
  • Travel for Invitation sprints = $34,000
    • 8 people at $2000/person = $16,000 X 2 sprints = $32,000. This includes airfare, room and board for a 2 day sprint.
    • Rental of a meeting space for 2 days = $1000 X 2 sprints = $2000
  • Travel for Community sprints = $12,500
    • These include airfare, room and board for a 2 day sprint.
    • North America: 1 person at $1500 X 3 sprints = $4500
    • Europe: 1 person at $2000 X 2 sprints = $4000
    • Asia/Pacific: 1 person at $4000 X 1 sprint = $4000

Comments

Quick thoughts

agentrickard's picture

Ahem -- voters really need to leave some comments, please.

I need to review more closely, but I really like this idea. Is it possible to save costs by:

-- Doing some of it virtually?
-- Co-locating with other cons?

Oh, and drop by the IRC meeting on Thursday and you can introduce the topic.

http://groups.drupal.org/node/14657

--
http://ken.therickards.com/

Costs

add1sun's picture

I'll definitely try to make the meeting. My schedule looks clear for it right now.

RE: saving costs:
"Doing some of it virtually" -
Well I already intend to do a lot of virtual sprint work as it is, as mentioned. I can limit the number of physical sprints obviously, but I have seriously found that physical sprints are much more productive. Trying to get people in different time zones all organized and task focused online for more than an hour is honestly just exhausting and not something I can sustain. I'm not sure how I can get the level of focus and simple number of hours of time from people online. The Invitation sprints are not going to work if we don't actually meet at a physical location as far as I'm concerned.

The camp sprints are more optional but, again, I have found that being physically present for hours on end to not only explain but show people how to do things, as well as have free form discussion is key to getting people more engaged. I don't want to simply get a bunch of people working on docs tasks, but I really see the camp sprints as training grounds for new doc leaders that can spread sprints in their local groups/regions. I will be doing virtual sprint support as I can, but I really want to have a few physical "seed" sprints as well. If the costs seem too high, then I can cut the camp sprints from the proposal. The Invitation sprints are vital though, so the proposal is sort of meaningless if I can't get funding for those, and those are the bulk of the costs here.

"Co-locating with other cons"
Well the camp sprints are located at other events, which is by design. I don't see how co-locating the sprints at a con will help costs much. The only costs related to venue are $2000 for a meeting room on the Invitation sprints. I think it is very feasible to rely on donated space for these though, so I can cut that out of the proposal pretty easily. The real cost is simply getting the key people we need to the same location. Co-locating at a con doesn't really get us that unless for some reason, some of the people are attending the con. I personally don't know of any particular non-Drupal conferences that would work for that. I am against doing the sprints at DrupalCon because there is no way I will have the time or focus to devote to closed door sprints during a DrupalCon. I (and most other key people who may be there) have way too many responsibilities and distractions at a DrupalCon to make that reasonable. We could tack the sprint to the beginning or end of a DrupalCon, but frankly I am so burned out at cons as it is that I think that is a poor decision. We also need to keep in mind that quite a few key docs people do not make their living from Drupal and so do not have the resources to attend DrupalCon, much less other conferences generally.

I did try to cut the expenses on this as much as I could, particularly by donating my sprint time and assuming that sprint invitees would be donating time as well. The costs here are really about international logistics, which is why this is really hard to pull off without a source of funding.

Lullabot loves you

Learn Drupal online at Drupalize.me

Awesome answer

agentrickard's picture

Well, that clears up my doubts about expenses. Thank you.

I would love to see this type of proposal get some funding, so this will be an interesting trial.

Voting a 5.

--
http://ken.therickards.com/

I'd been reading this but

catch's picture

I'd been reading this but just realised I'd neither voted nor commented, 5/5 from me.

I think that improved

MatthewS's picture

I think that improved documentation is a laudable goal. I'd like to see this happen.

This proposal is fantastic.

ericgundersen@drupal.org's picture

This proposal is fantastic. There is nothing like being in the same room with people to make great things happen. This on the ground component is going to make this really work. I have given it 5 stars.

Awesome work Addi!

eric

I say this with a certain sense of irony...

TKS's picture

...since I'm one of those people who has joined the documentation team, sincerely intending to dive in, and then done very, very little. But this is a great project. Documentation is hugely important for spreading the Drupal love to non-developers, and helping potentially interested individuals and organizations claw their way up the learning curve.

The slew of new Drupal books is a big help on that front, but only online documentation can hope to keep up with the rapidly moving target that is Drupal. Eric touched on this above, but here's my editor's take:

  1. Writing good documentation is really, really hard.
  2. Writing anything by committee is also very difficult
  3. Documentation by committee via asynchronous emails, listservs and the odd IRC session warrants combat pay for Addi and the others who keep doing the heavy lifting.

Two days around a table could produce more good work than weeks of virtual collaboration. I give this one five stars.

Excellent!

emmajane's picture

Although I am an experienced open source documentation author, it was not until I'd attended the sprint organized by Add1sun at DrupalCon Szeged that I really dove into the Drupal documentation. Attending a face-to-face sprint really made me feel comfortable contributing on a regular basis to the documentation.

One of the things I like about this proposal is the combination of different types of events. Having a core team get together for a focused sprint seems obviously beneficial in shaping documentation overall on d.o. But I especially like the attention to community/local events. Not everyone can afford to attend a DrupalCon, but many will make the effort to attend a closer, regional event. I like the idea of having fewer people travel to more places to support community initiatives rather than forcing a large number of people to a single destination for in-person sprints.

As part of this initiative I would also like to see documentation written on how to host a local documentation sprint. (Choosing tasks, venues, getting people to attend, lessons learned from past sprints, etc.)

Agreed

add1sun's picture

Yep, I agree with the need for docs on how others can do sprints too. I can make this clearer as part of the 80 hours documentation creation in the proposal. That is what I am targeting: setting up others to feel confident and that they have the resources to spread doc sprints themselves. Rock on.

Lullabot loves you

Learn Drupal online at Drupalize.me

I voted, but did not leave a

Ian Ward's picture

I voted, but did not leave a comment yet (was short on time but excited for this). The following is why I give this a 5: I believe that the Drupal Handbook is the only resource with the potential to become the best Drupal user/developer resource. Getting the team together like this to sprint on documentation, attract new team members, as well as discuss how to better organize and grow the handbook over time is what will ultimately maximize the Drupal Handbook's potential. From a quick glance at the agenda, at a distance, I know there are discussions like what to do w/ internationalization and the handbook; Tasks like these are a lot of work to figure out, and do, and the plan above is the way to do it. Briefly about why the Drupal Handbook is the only resource w/ the potential to become the best Drupal resource: the community is there. The community is who leaves comments and gets into the details of work-arounds, errata, alternate methods, and intricacies that have so much value which ultimately attracts more contributors and better and better material. I also support the printed books that have been published. Obviously those help a ton of people. I have a few copies of a few of those at home and work. But there are also limitations w/ those; see http://www.wichay.com/2008/sep/09/relative-cost-drupal-books-different-c...

The work to be executed based on this proposal will be one of the best things for Drupal in the next year.

Ian

value-for-money

heather's picture

distributing the effort amongst people donating their time, and placing it within the conferences and spaces already receiving funding is a great idea. this would be a highly-valuable contribution, with a great return on the investment.

all the practical results aside, it is also about getting people together. i was also at the szeged docs sprint, and glad to help out in any way i could. i liked how it was organized to zerg a task in a short amount of time by a big group of people which would have taken hours of tedious work by one person. very satisfying from a participant's point of view. this is a great initiative!

and that's why i gave it 5 stars.

Excellent Idea, well scoped

dgorton's picture

As someone who has attended a Doc Sprint, I wholeheartedly support this effort and know that it has the potential to have a great impact for the entire community. Excellent idea.
5.

Drew Gorton
Gorton Studios

Great proposal

bonobo's picture

Great proposal, and great clarifications/details in add1sun's responses.

I also like emmajane's proposal for meta-documentation, as that makes this process more replicable -- hopefully to the point where it can become self-sustaining.

Voted a 5.


FunnyMonkey
Tools for Teachers

This one gets a strong nod

Senpai's picture

This one gets a strong nod from me. Nice idea!

What if, in the interests of lowering costs for travel, made a Doc sprint happen in two locations simultaneously, instead of just one? As I read your proposal, I started thinking that if everyone were in separate virtual locations, the meeting would peter out quickly and become unproductive in about 1.5 hours. Basing the sprint in 2 distinct locations, however, gives the sprinters the ability to engage in a two-way skypecast and maintain a real-time sense of direction and forward motion.

Maybe if there were two or three people that were within an hour's drive of each other, and another three or four people that all lives in the same city, the Sprint Organizer could fly into the city with the least amount of people, and coordinate the two day sprint via a live videostream. This wouldn't work with any more than two locations talking to each other, but it'd be a sight cheaper than flying 8 people into the same city and putting them up for the weekend, thus enabling the same amount of KDI monies to fund more doc sprints than the original proposal.

Addi, thoughts?

(/me volunteers to organize and supervise one of the first ones, be it in my town of San Diego, or abroad.)

______________________________
Senpai (my d.o account)
  ~ Build a better WorkHabit ~


Joel Farris | my 'certified to rock' score
Transparatech
http://transparatech.com
619.717.2805

Hm, I think the invite

add1sun's picture

Hm, I think the invite sprints can only really work if everyone is in the same location. Anything virtual for those, even between two locations is very hard to sustain for 2 eight-hour days. I also don't really think we are going to have people grouped together very closely. I'm open to argument on it but I feel pretty strongly about having one physical location. I also imagine that setting up international live videostream for two days could be a PITA and have its own costs as well.

Lullabot loves you

Learn Drupal online at Drupalize.me

can this effort and Dmitri's

dipen chaudhary's picture

can this effort and Dmitri's Drupal learning Resource proposal work in tandem?


Dipen Chaudhary
http://dipenchaudhary.com
http://playdrupal.com


Dipen Chaudhary
Founder, QED42 http://www.qed42.com Drupal development

I'm not sure

add1sun's picture

I'm not sure how the two proposals could operate in tandem since they have pretty distinctly different goals. Could you explain more about what you mean?

Lullabot loves you

Learn Drupal online at Drupalize.me

As the organizer of the search sprint...

robertDouglass's picture

... I can say with some confidence that the high front-end costs of bringing people together pay off in the long run. The chance to really work through tough technical issues together, build agreement on concepts and goals, and share tips and techniques, is invaluable. The members of the search sprint have managed to keep a steady flow of patches and search related work going months after the sprint, and I feel that this type of initiative is really a perfect fit based on my understanding of the Knight Initiative.

Sprints are key

farriss's picture

Sprints provide much needed task leadership, solution development and momentum for any topic much faster than can typically be achieved via remote collaboration. The expenses of each sprint are dwarfed by the value of the time that is volunteered and the outcome generated.

Improving the Drupal documentation is essential to our continued growth and success so I absolutely support the goals. This proposal is thoughtful and well reasoned and is an excellent candidate project for KDI. 5 stars from me.