The WebPlatform project has been discontinued when the Stewards partnership agreement ended in September 2015. This site has been frozen, and the assets we have created will remain.
Doc Sprint in a Box
What’s a Doc Sprint?
This document describes the planning and execution of a Web Platform Doc Sprint. While a doc sprint may be as simple as a small group of people gathering at someone's house or as elaborate as a full-blown event at a public venue, with fifty or more people, catering, speakers, swag, etc., for the purposes of this document a doc sprint is:
- A pre-announced, free event open to the general public where a group of ten or more people gather in one location at the same time to work on WebPlatform.org for an extended period and report the results of the work performed in a standard format.
This doesn't mean that a doc sprint can't be virtual or that it can't be a spontaneous event with fewer than ten people. But most of the information in this guide won't apply to such smaller-scale doc sprints.
The key deliverable common to all doc sprints is the report of the work performed. That means publicizing the doc sprint ahead of time and reporting the results shortly after the doc sprint. It's like a tree falling in the forest: if nobody knows about the doc sprint, it didn't happen. Do good, and let others know about it!
Goals of a Doc Sprint
- Onboard contributors: Recruit and train new contributors to WebPlatform.org and lower the barrier to contribution
- Write content: Get as much work done on WebPlatform.org as possible
- Give feedback: Collect feedback on improvements to the platform
- Report: Inform the community about what has been accomplished, report the feedback and next steps
- Have a lot of fun!
About this Guide
This guide captures the learnings from past doc sprints and advises those planning to run their own doc sprints. Some of the deliverables described are optional. For example, if you're running a doc sprint at your house with a group of friends, you don't need a sponsor and may not need t-shirts, catering, etc. Simply use your own judgement and/or ask others via IRC and the public list if in doubt.
Also, there are two ways to read this document. You could start with the General Considerations section or jump down to the more comprehensive Timeline section, which puts things in order and links back to the considerations wherever needed.
There should be at least two people in primary roles running the doc sprint (you can assign more than one person per role):
- Logistics Coordinator
- Content Coordinator
The Logistics Coordinator will focus on all things needed to make the event happen, such as coordinating location, staff, catering, front-door reception, or life-saver stuff such as contacting the local IT admin to deal with network issues. The person in this role can of course contribute content during the doc sprint; however, this person would prioritize (for example) organizing more beer for the crowd over answering content questions. The Logistics Coordinator's primary focus in terms of general goals is 1, 3, and 5: make contributors happy, report accomplishments, and generate fun.
The Content Coordinator will focus on general goals 2 and 4, content and structure: a plan for what the group will focus on, answering questions that contributors have about authoring content and working with the wiki, and guiding additional content coordinators to lead work groups and help organize the work for the day. As a rule of thumb, a ratio of up to 1:12, 1 coordinator guiding 12 contributors, works best. A work plan and related docs allow contributors to answer many questions themselves; see the Zurich plan or the Berlin plan as examples. We recommend a planning meeting of coordinators focused solely on content.
Choosing the perfect date and time for your event is impossible. People prefer either to contribute on weekdays during work time, if their employer supports them, or on weekends, during their free time. Some like to work in the morning, some prefer the afternoon. Also, location, time of year, and other implications may apply. Consider the following:
- Decide if you are running a one- or two-day doc sprint. Two-day sprints may attract more attendees, if scheduled, for example, on Friday and Saturday (thereby including both a workday and a weekend day). Don’t separate the days into distinct events, but briefly repeat introductions and operating mechanisms on day two. Make it clear that participants don’t have to attend both.
- Try attaching your doc sprint to a bigger event, such as a conference. People are already in town and might be persuaded to add the doc sprint to their itineraries (see Colocated Events).
- Check in with folks on the IRC and the public list to see if your dates work for potential volunteers, experts, or attendees, and are in line with other WPD happenings.
While it sounds like a rad idea to have a doc sprint on the beach, the intense sunlight, sand, and smear of suncream on laptops might be a problem. Other than the obivious, here are some things to consider when choosing a location:
- Power: People need electricity to run their laptops. Provide at least one power outlet per attendee (and maybe more, for their other devices), and make sure extension cords are available.
- Network: Other than power, this is by far the most important asset for your event. Remember: you will be working online. No network, no uplink, no doc sprint. Ensure the capacity of the LAN, WLAN, and uplink bandwidth are sufficient for your event. Where possible, use copper instead of WiFi. Have IT administrators on hand. You should not use a location where the network might collapse when your recruiting efforts are just a bit more successful than expected!
- Audio/Video: You will need A/V Equipment proper to your location to show slides and amplify presentations. Ideally this is available on premises. Remember the international power plug adapters!
- Security: Make it clear that everybody needs to mind his/her own belongings. If attendees need to sign in to enter the building, make sure you understand and communicate the process and, if necessary, hire a person to receive and authorize attendees at the front door; a TaskRabbit works well for this.
- Catering: This depends on what you want/can provide for the event. The location may have its own kitchen and staff or you may have to work with an external contractor who brings the food, plates, and utensils. Watch out: some locations restrict you to their "own" (or union) contractors (i.e., they don’t allow you to call your favorite local pizza place); some won’t allow you to bring your own beer. Be sure you check this beforehand.
- Staff: While this might not be a location requirement, keep in mind that you will need people to take care of the aftermath of the doc sprint as well as the setup. It can help if this is provided by the location and thus a no-brainer for you, especially if you want to leave the location for drinks afterward instead of disassembling and cleaning up the place. Again, a TaskRabbit may work for this.
- Directions: Pick a location that can be reached easily. If it is not easily accessible, or has limitations like no parking spaces, be sure to communicate before hand (see Registration and Communications). Provide a map to the event, with options for public transport, if possible.
- Facilities: Be sure there there are enough restrooms for the size of your group and that people can find the restrooms easily; put up signs with arrows if necessary. Provide separate areas where a few participants can gather for conversations. Think carefully about how many people can effectively work a whole day at the venue.
- Company workspaces (after hours, or on weekends): this helps promote a company, and they are often happy to offer space
- Community centers
- Coworking spaces
- Conference venues (see Colocated Events)
- Universities and other academic settings
Consider scheduling a doc sprint close to a relevant, local event, such as a web development conference or W3C working group face-to-face meeting. You may be able to use some of the event space, or catering; you may be able to announce your doc sprint through the event's PR and announcements, and attract some of the same attendees. Scheduling your doc sprint before the main event might get better engagement than after (when everybody's head is about to explode, from the conference or the conference party, or both). On the other hand, many conferences are scheduled for the last two days of the week, so attendees are more likely to stay through Saturday, perhaps with some time to donate to WPD and the community.
However, be careful not to compete with any aspects of the main event, since attendees of that event are less likely to stick around to work at a doc sprint when there are other things to be done. Instead, organize the doc sprint on one of the subsequent days, or during a paid workshop day, or as a free event open to the public if the main event is for-pay.
Always be respectful to the main event organizers; do not undermine their goals, or draw people away from their event. Treat a doc sprint as a supplement, not a rival.
Here are two examples on colocated doc sprints of the past:
- As a workshop, prior to the regular event: http://2013.frontendconf.ch/workshops/
- As a partner event, after the regular event: http://fronteers.nl/bijeenkomsten/2013/web-platform-doc-sprint
In both examples, the conference helped to announce the doc sprint to attendees in its regular event communication with e-mails, tweets, and other messages. Also, a doc sprint and its world-wide visibility via the W3C and Web Platform Stewards PR can help a conference gain more visibility. This is a classic win-win and should be played as such, like a partnership.
While it is already fun to contribute for the greater good, attendees appreciate other reasons to attend a doc sprint, such as the following:
- Recognition: Include your contributors' names in the results report and highlight outstanding accomplishments; also, encourage them to earn their Firestarter badges (added to their user pages with the tag "[[Image:css-firestarter-badge-simple.png]]" ).
- Swag: T-shirts, stickers, gadgets (possibly available through one of your sponsors, including the Web Platform Stewards) and the like should be available.
- Raffle prizes: Various tech-related goodies (possibly available through one of your sponsors, including the Web Platform Stewards). Make it clear that only contributors are eligible for the raffle.
- Catering: Try to provide at least free drinks and simple snacks such as fruits and energy bars. It's okay for attendees to break away independently for lunch, but remember that any time they leave the venue they may not come back.
- Networking: Foster people's information exchange by having a reception or party after your event. It should be easy to find a sponsor for drinks, and most of the nearby bars are happy to keep open a corner for 10, 30, or 60 customers as long as you prearrange it with th em. Make sure the organizers and speakers are available to attendees as much as possible.
- Meeting notable people: Similar to networking, if you have notable attendees (see Guest Stars), many people will enjoy meeting them; these might be specification editors, or well-known developers or designers. For some people, even just meeting and working alongside someone from the stewards group may be exciting.
Registration and Communications
- "Come any time! Stay as long as you want!" Emphasize this in all communication. Many people won't come to a doc sprint because they think that they have to be there all day.
- The doc sprint is an introduction; you want participants to stay involved, even if you can only contribute a little bit at a time.
- Advise people to bring their own computers and especially a power adaptor. Send a reminder 24 hours before the event just for this! Make this very clear, and have it as one of the first items people will read in your communication; attendees have showed up without a computer to work on in the past!
- Ask attendees not to run their own hotspots, but invite them to use own cellular data for secondary devices so they come prepared.
- Ask people to return tickets (especially on free events) if they cannot make it to the event. Include this in all communications but make sure to send out a dedicated message asking people to free up vacant tickets some days before the event so you can align catering.
- Ask people to add themselves to any helpful social media service you are using, such as Lanyrd or Meetup. Provide these links to attendees.
- If you are using Eventbrite, use the survey feature to run three questions against registrants:
- Have you already added yourself to our Lanyrd page?
- Do you have any food requirements (vegetarian, allergies)?
- What is your t-shirt size (if you plan to provide such swag)?
- Make sure to provide a contact for people to ask questions.
- Provide links to registration pages.
- Share any links to the announcement and registration pages to the WPD public list.
- The hashtag we used for Web Platform Doc Sprints in the past is #WPDS; be sure to let your attendees know ahead of time and on the day of the event. And ask them to be active on social media! Other useful social media strings are:
- Google Plus: +WebPlatform Docs
- If you want to collect images taken by attendees, consider announcing a specific location, service, or tag to use while posting. It makes reporting much easier!
Follow up the doc sprint with a quick survey.
- Here's the survey template you can copy.
- Make a copy of this template and rename it for your doc sprint, for example, "WPDS - Amsterdam, Oct. 12, 2013". In your copy, toggle "Not accepting responses" button to "Accepting responses".
- If you use all of the same questions, we can track changes over time. But you can also add and subtract questions to fit your needs.
- Here is the WPD Survey page.
- Some event registration systems offer survey capabilities, and you can also create a Google Form for this purpose.
Be sure to provide thank-you notes to attendees. Here is one from a previous sprint:
- Thank you for attending the Web Platform Documentation Sprint last November. With your hard work we made over 800 changes to the site!
- Because it was such a great event, we'd like to let you know that we will be hosting another Web Platform Doc Sprint next month and we hope you will once again decide to participate.
Please note that doc sprints are meant to be free events! If you can’t afford the space or catering, please consider asking a steward or other sponsor to help fund the event; please do not charge attendees for the event, as that violates expectations and trust in the community. Participants are volunteers.
Registration Numbers and No-Shows
A normal range of registrants can vary widely. Depending on the size of the venue and the success of advertising, you can usually count on 30–100 registrants, with an actual attendance rate of 40–50% (i.e., 50–60% of people registering will not show up).
On the day of the event, send out a note to all no-shows.
- Tell them the doc sprint just kicked off, and "here is how you can participate if you did not make it to the event".
- You can point them to the work plan (see the Zurich plan, for example) created by the Content Coordinator.
Below is a general timeline for items you should plan, prepare, and execute before, during, and after a doc sprint.
|2 months|| Commitment to day(s)
||First and foremost, get a date, place, and people to staff the doc sprint. Compare Event Roles. Check in with folks on the IRC and the public list to see if your dates work for potential volunteers, experts, or attendees, and are in line with other WPD happenings.|
|2 months|| Sponsor(s) and Budget
If you can get a big company with deep pockets to pay for food, swag, etc., get them to sponsor a doc sprint!
|2 months||Event registration system established and available||As much as possible, use only one system to prevent duplicate registrations. Also make sure other people don't set up duplicate registrations.|
|2 months|| Announcement
Should include the what, why, where, when, and how to get involved.
|Get the word out. Show up at a group meeting and give a quick lighting talk about WPD and announce the doc sprint.|
|1.5 months|| Swag
Have quantities, a design, and a vendor established for t-shirts, stickers, etc.
See the list of Swag Vendors for your location.
|By this time you should have a rough idea of how many t-shirts and stickers to print, based on initial registrations. Most vendors need about six weeks to print and deliver.|
|3 weeks|| Guest speakers
Get commitment from community luminaries to drop by and do a presentation. If the doc sprint follows a conference, speakers may be able to commit even earlier.
|Michael Mulaney, CEO of Sencha, gave a talk on SVG filtering at a San Francisco doc sprint in April 2013. Great stuff!|
|3 weeks|| Content
Have a plan for what people will work on. The Content Coordinator should hold a meeting with other coordinators to develop the plan.
|The Getting Started page has lists of content that needs attention. These may need to be sanitized prior to the doc sprint. Run through the lists and make sure the articles cited are current. Also, email the public list to ask about current projects & needs.|
|2 weeks|| Food & Beverage
Have a vendor, menu, and quantities ready. See the list of Caterers for your location.
|Registration information should give you a good idea of how much food and beverage. You can always update your order as you get closer to the doc sprint.|
|2 weeks|| Reception & check-in
You'll need a dedicated person to man the front door, take attendance, and hand out badges. This person should be prepared to handle emergencies, have a plan for dealing with disruptive attendees, and be able to contact site security.
|A TaskRabbit works well for this. Don't delegate this to a doc sprint leader; it will be all they will do, which is not the best use of their time.|
|1 week|| Reminders
||To help with catering and planning make sure to remind people in all communications, but especially when it gets close to the event, to update their RSVPs and release their spots if they are not coming.|
|Zero (day of sprint)|| Agenda
Remember that the results of the doc sprint, communicated in the blog, will include a summary of the work performed and some anecdotes from the day. Leaders/coordinators should be on the lookout for interesting bits to include in the blog.
|Zero + 1 day|| Stats and summary
See Results for more information about gathering and compiling metrics
|Zero + 3 days|| Blog post and social media
Write up the results of the doc sprint and relate amusing anecdotes. See past blog posts, below for some examples. Use social media (Twitter, G+, Facebook) to link to the blog post
You’ll want to get an accurate count of participants and the work that they do. There are at least three options to do so (maybe a combination of them is golden).
Option 1: Piwik
Throughout the doc sprint, display the current Piwik report on current progress. The report measures:
- Total number of pages edited
- Total number of words added
- Total number of words subtracted
- Top five contributors pages edited
- Top five contributors words added
- Top five contributors words subtracted
- Pages edited per content area (determined by URL), e.g., css/properties
Option 2: Recent Changes Page
Alternatively, you can compile results by hand from the Recent Changes page, but that can be difficult. Keep in mind that the reports generated here are limited as to the number of page edits reported (you can get as many as 1,500) and the number of days back the report will show (you can go as far as 90 days or more), and combining multiple days with many page edits exceeds the capacity of our data server (you can't combine 1,500 edits and 90 days; you'll get a 503 error). So if you rely on this as a source for results metrics, be sure to compile those results as soon after the doc sprint as possible, otherwise you may not be able to get all the results reported here.
Option 3: The Web Platform Doc Sprint Dashboard
Built by community members for the first European doc sprint in Berlin, you can display this dashboard during the doc sprint. This is a web page that uses the MediaWiki API to display metrics from WebPlatform.org in time-lined graphs, such as:
- Agenda of the day (free text display)
- Number of Edits
- Bytes added/removed
- Leaderboard of participants with most edits during doc sprint
- Leaderboard of lifetime edits across doc sprint participants
- Newbies vs. Lab-Rats
You can also add general information such as Wifi credentials, important URLs or contact information to a sidebar that is permanently displayed. Of course you can extend the code as well — just grab it on GitHub. There are some screenshots there as well.
Do good and shout it out
Broadcast milestones during the doc sprint. Give a shout-out when your contributors check in the 25th completed topic or when the tenth contributor joins online. Participants will love to hear that their "team" is making progress and that their efforts are part of a successful endeavor. The dashboard is a nice way of constantly pumping out the latest "competitive data".
Information that measures quality
Because quality is such a subjective term, capturing and reporting on the quality of work done in a sprint can be difficult. There are objective measurements you can collect that do indicate enhancement of quality, however: number of broken code samples fixed, topics reviewed successfully by industry experts, topics in which SEO optimization has been completed, etc.
Images of the event
A picture's worth a thousand words, and photos from a doc sprint help bring your event to life for community members who couldn’t attend and for attendees who want to reminisce after the event is completed. First things first: you must get permission from any person or facility you want to capture in a photograph or video in order to use that image. And be specific: whatever images you place on Webplatform will be available under the CC-BY license. Having said that, reports are greatly enhanced by photographs of the community hard at work or taking part in whatever social activity that is a part of your event. Include items from Flickr and other sites, assuming you have the requisite permissions.
Don't forget to include samples from social media for your report. You've probably been using Twitter and other social media to advertise your event, communicate with the community, and boast about accomplishments. Did you use Eventifier to capture all the goodness? 140 characters can pack quite a wallop. Capture that goodness.
We have yet to have a doc sprint after which an attendee responded, "No comment," when asked about the event. Get some good quotes from your participants and capture them. Find out if you can use their name if you publish their words, too.
At the end of the doc sprint, people are interested how it went, what worked, and what didn't. Please provide a brief report, and include:
- Event Closer: This is for the attendees at the end of the event itself; a preliminary report with leaderboards, number of pages edited, and callouts to specific contributions of high quality, to thank, reward, and encourage contributors.
- Community List: Send a notice to the public list, which may include discussion about what worked well and what didn't, to spur conversation.
- Blog Post: A blog post will be the most permanent and public record of the event, and may also be the most complete.
- Go/Stop: Any lessons learned or improvements identified. This is especially useful if the event didn’t go as anticipated.
The results measured over the doc sprint will already contain most of what you need to communicate. Freeze it, keep a copy, and publish out the results with your report. You'll also want to report:
- Total number of attendees
- New contributors signed up
- Contributor with most words added
- Contributor with most words subtracted
- Contributor with most pages edited
Past Blog Posts
In order for you to post to the WebPlatform blog, you'll need a separate account. Send a request to firstname.lastname@example.org to have an account created for you. Below are some examples of previous doc sprint blog posts.
- February 8/9, 2013 Berlin
- February 23, 2013 San Francisco
- June 22, 2013 Seattle
- August 28, 2013 Zurich
- October 12, 2013 Amsterdam
- November 3, 2012 San Francisco
- December 12, 2012 Mountain View
- April 3, 2013 San Francisco
- August 28, 2013 Zurich
Content Plan and Topic
Announce your topic when you advertise the event to focus attendees and improve productivity, by bringing in people who are interested in that specific topic, and letting them know exactly what they can expect to work on. Even experts, faced with a blank canvas, may not know where to start, so a paint-by-numbers approach can help everyone get started.
Slides, Summary Page and Short URLs
Regardless of whether you are just planning to do an overview of the housekeeping rules or are having one of your experts give a full featured introduction to WebPlatform.org, others have built slidedecks before you, and these are available in full featured WebPlatform.org design and available for you to use and modify.
If you have themed your event and a content plan is established, it helps to list all the information you are planning to give out in an introduction on the event on a Wiki page as well. This is not only helpful for people to review after they listened to your presentation, it also helps to onboard people that join in late and have missed the introduction. Here are the Berlin and Zurich examples of those pages.
Instead of communicating lenghty URLs in your introductions, it is much easier to shout out a short URL to the room: "Hey, you'll find all necessary instructions on wpd.mx/intros!". This is why we use a Short URL service built by community contributors, and you can do as well. You can find it on GitHub, and changes are active within minutes: wpd.mx shorturl repo.
Doc sprint events are relatively expensive, financially and logistically; they are important, but should be a supplement and support for everyday contributions and community engagement. One of the goals of a doc sprint, besides driving content, is to convert skilled and interested people into active contributors and community members.
- Training in conventions and editing
- Showing how to find areas that need contributions, like Web Platform Wednesdays
- Overcoming reluctance to add content by empowering contributors (and getting them over the hump)
- Rewarding them at the time, and continuing to offer small rewards for future contributions
One of your pre-event communications should have information for newcomers about joining WebPlatform, setting up an account, and should contain a few links to topics that have good information for those new to the project, such as the Editing Guide home page. Don't overwhelm people, but do give them the opportunity to get started on their own. This will greatly reduce the number of volunteers who need to have their hand held on the day of the event, enabling you to concentrate more fully on the theme.
When planning a doc sprint, you should first let the community and community leaders know that you are interested in planning an event, so we can:
- Provide promotion (see Timeline)
- Coordinate with other events, either other doc sprints or local events colocated with your doc sprint
- Help in picking a theme and content lists
- Provide swag (stickers and t-shirts)
- Contacting Stewards
The first point of contact is the W3C community mailing list. A message there will best get the attention of community leaders. Provide the names and contact information of the organizers, the location and date of the doc sprint, and your topics of interest. If you prefer to start the conversation more privately, for whatever reason, you can contact the community leaders (such as Doug Schepers (W3C) and others) offlist.
It's helpful for a doc sprint to have some experts involved. Having one or more well-known attendees can help promote the event, help provide expert advice to contributors, inform and entertain attendees, and even provide some high-quality content themselves.
If you know your theme, you can find experts, either local or from one of the stewards, and ask them to attend the event; these people are often quite busy, so don't be discouraged if you can't get a particular person; just ask them if they know anyone who might be able to attend. Some experts might include: specification editors; working group members; developer relations engineers or evangelists; conference speakers; book authors; or just well-known developers, designers, or bloggers. It may even be a prominent member of the WebPlatform.org community!
Often, the expert's employer will pay their travel expenses to attend the event, if it is related to their job.
Ask the expert to prepare a 15-20 minute talk on their topic for the afternoon of the event; this will be a reward to attendees, and will re-energize contributors after lunch. It also provides an opportunity for the expert to get feedback from the community.
Plan ahead for this, to make it easier to find someone. Ask the stewards and community leaders to help find someone if you don’t know who to ask.
Sometimes, you will get attendees who are disruptive. They may have good intentions, or they may not… either way, you need a plan to deal with them. For example:
- Social Butterflies: These are people who are just at the event to socialize, get food or swag, or to "check in" and be seen, without doing any work. They may sit quietly in the corner on doing their own unrelated thing until lunch, or they may engage with other people. So long as they keep to themselves, aren't too noisy, don't distract others, and are not occupying needed space, they are not a problem; just make it clear to them that they need to respect the event.
- Attention Seekers: These are people who want too much attention from the event organizers or experts. They may be contributing, or they may only be there to have discussions or even to challenge people. Give them enough time to make their intentions clear (they may just not be communicating well, but have something to offer), then politely explain that you need to do other work. Warn other event organizers about these people, so they know not to invest too much time on them; don't palm them off on other event attendees.
- Inappropriate Attendees: These range from homeless people looking for a meal to crazy people looking for a fight. If you have a registration desk and insist on having people sign up for your event this will help to scare off those kinds of folks. Let venue personnel handle these people.
Some of the swag that we might offer for attendees includes:
- toys (such as the WebPlatform erector sets Google offered)
Refer to the WebPlatfor.org logo page in creating designs with our logo.
Here is a list of vendors by country from whom you can order swag. In most cases, it is best to order items and have them delivered specifically for the doc sprint to avoid the hassles of maintaining a swag inventory and shipping stuff yourself. In some countries, like those in Latin America, it is illegal to import promotional material; it must be produced in the country in which it is delivered.