Open Help: Janet Swisher: Docs Sprints, Book Sprints, & Liberathons
Janet Swisher works on developer documentation at Mozilla.
What is a docs sprint?
A short period of time that people come together to work on documentation. Book sprints are focused on creating a book. Doc sprints are a natural extension of code sprints, hackathons, hack fests. Book sprints were originally for accelerating the book writing process, but have been used successfully for entire books. See FLOSS manuals.
There are studies for looking into the book sprint model for academic publishing.
Projects may or may not have the aim of creating a book.
Types of sprints
- combination – multiple local gatherings communication with each other
- fly-in – bringing in specific participants to the same place
- Janet is talking about docs sprints that she has taken part in or spoken to people about. She was first involved with the FLOSS manuals project, then started doing docs sprints at Mozilla. Mozilla is supporting Web Platform which does large docs sprints.
Planning a Sprint
- know your goals. You can have goals for your content and goals for your community.
- Pick a type and scope. Your goal will affect the type of sprint you have. Even if you have an open invitation you will have particular people you want to get involved.
- Pick dates and times
- Invite and promote – personal invitations to people you want to be there, then do a lot of promotion to get more people there
- Handle logistics - depends on the type of event you have, the budget etc
- schedule around the key people you want involved
- you can attach a docs sprint to another event
- doesn’t work to do a docs sprint during another event
- how long? Books sprints are typically 3-5 days. Docs sprints at Mozilla are typically 2 days for a virtual sprint and 3 days for an actual sprint.
- Atlassian have had sprints in different offices all over the world at the same time.
Sarah Maddox’s slides about “Docs Sprints: The ultimate in collaborative documentation development”
- People involved with QA
- Get users involved to act as guinea pigs
- have an editor to tidy things up as you go
- invite people personally – people won’t commit several days to a docs sprint without them asking them to
How do you get the docs you need?
- get people to work together
- the point is to work collaboratively
- pair up a writer and an engineer, or a writer and a user
Tools you might need
- A collaborative writing platform – e.g. Etherpad
- Task tracking
- Mailing list
- Webinar or video conferencing
- Code repository – make sure you have a place to put stuff
Things to do during a sprint
- Kick off meeting – look at the goals, go round the table and find out about people.
- Checkpoints – what has happened for far? Is anyone hitting roadblocks?
- Teaching sessions – teach people about the platforms, a particular style of writing, how to do tutorials. Breaks things up so it’s not just slogging away.
- Doc development
- Fun – organise fun outings or have spontaneous things
- Show and tell - ask people to go through what they did, talk about any problems
- Retrospective - either during the sprint or afterwards get people to reflect on what went well and what could be done better next time
What to do after the sprint
- if you don’t write a blog post, it didn’t happen – write a blog post, talk about what happened, highlight the content and thank the people
- make sure people feel appreciated
- get closure
- shout about it
- thank everybody