Doc sprints: The ultimate in collaborative document development
•Descargar como PPTX, PDF•
6 recomendaciones•6,549 vistas
This session discusses how to plan and run a successful doc sprint. The result is high-quality documentation, happy customers, and an enhanced reputation for your tech comm team.
Recomendados
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (8)
Destacado
Destacado (19)
Similar a Doc sprints: The ultimate in collaborative document development
Similar a Doc sprints: The ultimate in collaborative document development (20)
Más de Sarah Maddox
Más de Sarah Maddox (15)
Último
Último (20)
Doc sprints: The ultimate in collaborative document development
- 1. The ultimate in collaborative document development 1Doc sprints, by Sarah Maddox
- 2. People Time Documents 2Doc sprints, by Sarah Maddox
- 3. Doc sprints, by Sarah Maddox 3 A story about our developer documentation
- 4. Broken docs • Too few • Out of date • Inconsistent • Not hitting the spot 4Doc sprints, by Sarah Maddox
- 5. Developers do know Their audience The subject matter 5Doc sprints, by Sarah Maddox
- 6. They don’t know Where to start How to write a tutorial Whether it’s cool 6Doc sprints, by Sarah Maddox
- 7. BookSprints.net 7Doc sprints, by Sarah Maddox
- 8. BookSprints.net http://www.booksprints.net OLPC http://wiki.laptop.org FLOSS Manuals http://flossmanuals.net Atlassian http://confluence.atlassian.com/display/DOCSPRINT 8Doc sprints, by Sarah Maddox
- 9. OpenStack https://wiki.openstack.org/wiki/DocSprint Mozilla https://hacks.mozilla.org/?s=doc+sprint WebPlatform.org http://www.webplatform.org 9Doc sprints, by Sarah Maddox
- 10. The biggest sign of victory is how many pages I managed to delete! 10Doc sprints, by Sarah Maddox
- 11. Doc sprints, by Sarah Maddox 11 And why people take part
- 12. Developing a new tutorial that hits the spot Contact between customers and organisation Learning from experts Helping people Fixing stuff 12Doc sprints, by Sarah Maddox
- 13. 13Doc sprints, by Sarah Maddox Along with the immense challenge it presented personally, this was also a chance to work on a product and a team I’ve never worked on/with before
- 14. Doc sprints, by Sarah Maddox 14 Walking and talking agile
- 15. 15Doc sprints, by Sarah Maddoxhttp://agilemanifesto.org
- 16. Agile techniques Timeboxing Self-organising teams Efficiency Structure 16Doc sprints, by Sarah Maddox
- 17. Short period of development Shippable product by the end Planning-meeting at the start Retrospective at the end 17Doc sprints, by Sarah Maddox
- 18. Doc sprints, by Sarah Maddox 18 It’s all about the people
- 19. When to start Initial, 2-3 months ahead Full-on, 2 weeks ahead 19Doc sprints, by Sarah Maddox
- 20. 20Doc sprints, by Sarah Maddox
- 21. Developers Support engineers Product marketing Business analysts CEOs 21Doc sprints, by Sarah Maddox
- 22. Community developers Community authors Partners Technical writers Fans 22Doc sprints, by Sarah Maddox
- 23. Make it cool Use every channel available Target individuals Give plenty of warning Have some material ready Remind people 23Doc sprints, by Sarah Maddox
- 24. A designer, limited-edition, Atlassian doc sprint T-shirt. No-one else in your ‘hood will have one like it! Eternal recognition as author. Your name will appear as author of the tutorial on the Atlassian documentation wiki. Kudos from the Atlassian technical writers. We’ll write up our results on the Atlassian blog and you’ll be inducted into the Doc Sprint Hall of Fame. Learning while you write. We’ll have some Atlassian developers on tap to help us over the sticky spots. Pair with a technical writer to get those words buzzing. Chocolate. Indubitably, there will be chocolate in there somewhere. 24Doc sprints, by Sarah Maddox What will you get out of it ?
- 25. A designer T-shirt No-one else in your ’hood will have one like it! 25Doc sprints, by Sarah Maddox What will you get out of it ?
- 26. Eternal recognition Your name will appear as author of the tutorial on the Atlassian documentation wiki. 26Doc sprints, by Sarah Maddox What will you get out of it ?
- 27. Kudos from us The Atlassian tech writers will write up our results on the Atlassian blog and you’ll be inducted into the Doc Sprint Hall of Fame. 27Doc sprints, by Sarah Maddox What will you get out of it ?
- 28. Learning We’ll have some Atlassian developers on tap to help us over the sticky spots. Pair with a technical writer to get those words buzzing. 28Doc sprints, by Sarah Maddox What will you get out of it ?
- 29. Chocolate Indubitably, there will be chocolate in there somewhere. 29Doc sprints, by Sarah Maddox What will you get out of it ?
- 30. 30Doc sprints, by Sarah Maddox we may not get the book we thought we would going in, but by the end we will get the book we need
- 31. Focus Wish list Templates Style guide Technical guidelines 31Doc sprints, by Sarah Maddox
- 32. 32Doc sprints, by Sarah Maddox Wish list
- 33. Collaboration platform Communication plan Development environment Chat, video conferencing, webinars, email Room and facilities Catering Schedule and venue details 33Doc sprints, by Sarah Maddox
- 34. 34Doc sprints, by Sarah Maddox Involve people early Hot tip
- 35. Doc sprints, by Sarah Maddox 35 It’s still all about the people
- 36. Global sprinting Australia West, central and east USA Russia Israel United Kingdom Germany Denmark 36Doc sprints, by Sarah Maddox
- 37. Different locations Round-the-clock time zones English as second language 37Doc sprints, by Sarah Maddox
- 38. Different locations Round-the-clock time zones English as second language 38Doc sprints, by Sarah Maddox Flexibility Schedule Mentoring Technology
- 39. Macro tekkie Early sprinter Bent rules Ellis "Alpenmilch" Pratt 39Doc sprints, by Sarah Maddoxhttp://www.cherryleaf.com
- 40. Remote in Russia Love for user guides Tech writer Katya 40Doc sprints, by Sarah Maddox
- 41. Alone in Amsterdam Add-on expert from aevolu Travelled from Büdelsdorf Andreas "Ritter Sport" Spall 41Doc sprints, by Sarah Maddoxhttp://aevolu.com
- 42. 42Doc sprints, by Sarah Maddox Every day Standup Teaching Development Fun Lunch Presentations Retrospective Kick-off
- 43. Time Activity 8:00 Tutorial development 9:00 Sprinter meeting and webinar (“standup”) 9:30 Tutorial development 12:00 Catered lunch 13:00 Get your stuff ready for the presentations! 15:00 Presentations and retrospective 17:00 Late webinar with Amsterdam 43Doc sprints, by Sarah Maddox https://confluence.atlassian.com/display/DOCSPRINT/ Schedule+-+Doc+Sprint+August+2012
- 44. All in one room or via VC / webinar Two kick-offs if necessary Round-the-table Templates and guidelines Schedule Technical environment 44Doc sprints, by Sarah Maddox
- 45. Short What you did yesterday What you plan to do today Roadblocks Further discussions after standup 45Doc sprints, by Sarah Maddox
- 46. Documentation techniques Templates Source repository Best practices 46Doc sprints, by Sarah Maddox It’s all about getting the best out of sprinters, and giving them something in return
- 47. Fun and coolth Theme Haiku Weird and wonderful Lunch and late pizza 47Doc sprints, by Sarah Maddox
- 48. "This is the doc sprint presentations, right?“ "Yes, mate. We're going to talk about documentation for the next two hours. It's going to be awesome!" 48Doc sprints, by Sarah Maddox Presentations
- 49. 49Doc sprints, by Sarah Maddox What went well What could have gone better
- 50. Doc sprints, by Sarah Maddox 50 Teamwork Co-location Pairing Organisation Duration Doc maintenance Templates More teaching More promotion More pairing... What went well What could have gone better
- 51. More pairing 51Doc sprints, by Sarah Maddox The more pairing we do, the greater the shared learning!
- 52. Doc sprints, by Sarah Maddox 52 It ain’t over until the last doc sings
- 53. 53Doc sprints, by Sarah Maddox Decide on tech writer and/or engineer review Don’t be too picky Remember the audience Get it done during the sprint
- 54. Blog posts Tweets T-shirts Chocolate Hall of fame 54Doc sprints, by Sarah Maddox If you don’t blog about it, it didn’t happen
- 55. Doc sprints, by Sarah Maddox 55 Everybody loves them
- 56. Doc sprints, by Sarah Maddox 56 Multiple authors Ease of use Notifications Commenting Permissions Confluence Another wiki CMS Booki Office? Requirements Tools
- 57. HipChat Tea Party Google Talk IRC / Jabber 57Doc sprints, by Sarah Maddox
- 58. Google Groups (?) Self-compiled mailing list 58Doc sprints, by Sarah Maddox
- 59. Webinar versus VC GoToWebinar Simultaneously for: • Kick-off meeting • Daily standups • Learning sessions • Presentations • Retrospective 59Doc sprints, by Sarah Maddox
- 60. Bitbucket GitHub 60Doc sprints, by Sarah Maddox
- 61. Doc sprints, by Sarah Maddox 61 Knowing when you’re onto a good thing
- 62. Innovation register A whole day Funny hats Presentations Implementation 62Doc sprints, by Sarah Maddox
- 63. Doc sprints, by Sarah Maddox 63 Developers QA engineers Product managers Technical writers And all Test plan Kick-off meeting Collaboration tool Chat room Issue tracker Who What
- 64. Team ownership Team building Doc verification Late changes Bugs in app 64Doc sprints, by Sarah Maddox
- 65. Doc sprints, by Sarah Maddox 65 Plan Collaboration tool Screenshot tool Enjoyment Team spirit Ownership Awareness > ideas Burnout avoided Preparation Results
- 66. Doc sprints, by Sarah Maddox 66 From the experts
- 67. 67Doc sprints, by Sarah Maddox Around noon on the second day of the First Book Sprint we hear a knock on the door. Here is the set up, we're working from a hotel room in a complex called IMA Design Village, on the 5th floor of a redeveloped late 19th Century factory building with a jerky elevator and nothing to indicate where we are. http://en.flossmanuals.net/collaborative-futures/ch046_knock-knock
- 68. 1000 edits 400,000 bytes moved 40,000 new words 51 new contributors 57% non-local 4 future doc sprints 68Doc sprints, by Sarah Maddox http://lists.w3.org/Archives/Public/public- webplatform/2013Feb/0120.html
- 69. Doc sprints, by Sarah Maddox 69 Prizes Food and drink Cool swag Just go SFHTML5 meetup http://www.sfhtml5.org/ Running a sprint Taking part https://twitter.com/peterlubbers
- 70. 70Doc sprints, by Sarah Maddox “Oh, you are working on GNOME! I don’t like GNOME 3, let me troll you.” ... then we got to talking... Face-to-face interaction win. Aside from the initial need to deploy anti-troll measures, it was a successful event. http://j1m.net/2012/12/28/chicagoans-and-gnome-part-3/
- 71. Doc sprints, by Sarah Maddox 71 The infamous “for more information...”
- 72. Why do people write free documentation? by Andy Oram: http://onlamp.com/pub/a/onlamp/2007/06/14/why-do-people-write- free-documentation-results-of-a-survey.html Experiencing the Atlassian Doc Sprint - Aug 2012, by Swapnil Ogale: http://icreatedocs.blogspot.com.au/2012/09/experiencing-atlassian- doc-sprint-aug.html We Did It: Zero to Book in Five Days, by Anne Gentle: https://www.openstack.org/blog/2013/03/we-did-it-zero-to-book-in- five-days/ 72Doc sprints, by Sarah Maddox
- 73. Atlassian doc sprint wiki: https://confluence.atlassian.com/display/DOCSPRINT/ How to plan a doc sprint: http://ffeathers.wordpress.com/2012/09/07/how-to-plan-a-doc-sprint/ A big hairy task list for planning a doc sprint: http://ffeathers.wordpress.com/2012/09/07/a-big-hairy-task-list-for- planning-a-doc-sprint/ HipChat: https://www.hipchat.com/ Tea Party: http://tea-party.appspot.com/ 73Doc sprints, by Sarah Maddox
- 74. Google Talk: http://www.google.com/talk/ GoToWebinar: http://www.gotomeeting.com/fec/webinar Booki: http://flossmanuals.net/booki-user-guide/ Confluence: www.atlassian.com/software/confluence Bitbucket: https://bitbucket.org/ GitHub: https://github.com/ 74Doc sprints, by Sarah Maddox
- 75. Doc Sprint Mountain View, by Peter Lubbers: http://blog.webplatform.org/2012/12/doc-sprint-mountain-view/ Recap of Web Platform Doc Sprint Berlin, by Andre Jay Meissner: http://www.google.com/url?q=http%3A%2F%2Flists.w3.org%2FArchiv es%2FPublic%2Fpublic- webplatform%2F2013Feb%2F0120.html&sa=D&sntz=1&usg=AFQjCNG DrM5Zap7v4gWWyT1Xfu_Iu5c_dg 75Doc sprints, by Sarah Maddox
- 76. Innovation sprint: http://ffeathers.wordpress.com/2010/07/03/technical-writers-hold-an- innovation-sprint/ Documentation blitz-test: http://ffeathers.wordpress.com/2010/12/04/a-blitz-test-of-the- documentation/ Documentation blitz, by Edwin Dawson: http://blogs.atlassian.com/2011/09/interviews_from_the_jira_screensh ot_doc_blitz/ 76Doc sprints, by Sarah Maddox
- 77. Twitter: @sarahmaddox http://twitter.com/sarahmaddox SlideShare: http://www.slideshare.net/sarahmaddox/ LinkedIn: http://au.linkedin.com/in/sarahmaddox Blog: http://ffeathers.wordpress.com Other blog: http://travellingworm.wordpress.com/ 77Doc sprints, by Sarah Maddox
Notas del editor
- “Doc sprints: The ultimate in collaborative document development”A presentation by Sarah MaddoxFor STC Summit 2013, Atlanta Georgia.
- A doc sprint is an event where people get together to write tutorials and, often, code. The sprinters work together for a given period of time, usually two to three days, on a specific set of documentation. They tap into each other’s skills, get into the creative zone, have fun and write haikus.The outcome is a number of top‑quality tutorials, plenty of learning, and a set of new acquaintances.
- Setting the scene:To set the scene, I’d like to tell you a story.Are you sitting comfortably? Then let’s begin.On our developers’ site, we had some reference documentation, overviews, and tutorials.We knew that tutorials are key to a developer’s experience.No flies on us!Trivia:About the expression “no flies on us”.It means we’re wideawake and able to think quickly. Thereisnothingslowordullaboutus.Thisslangyexpression, which alludes to flies settling on a sluggish animal, was being used in Australia in the1840sbutdidnotappear in Americauntilthelastdecadesofthe1800s.
- Broken docs:But the tutorials were broken:Too fewOut of dateInconsistent in depth of coverage and styleNot hitting the right use casesTrivia:The fly is on a Scribbly Gum tree. Those scribbles are in the wood of the tree, and are made by a larvae wandering around in search of food. The smaller lines are when the grub is just hatched. It gets bigger as it feeds!
- Developers do know:We had some expert developers who knew documentation is a good thing.In the case of developer documentation and tutorials, developers know their audience.It’s themselves! Sometimes literally so – the same developers who write the documentation will later need it to develop their own products. In other cases, the documentation is targeted at external developers, who want to use the APIs and other frameworks available in our products.Developers are the subject matter experts. If we were writing the documentation, we would need to consult them.
- They don’t know:But our developers didn't know:How to start writing a doc.How to make a tutorial work.Whetherit's cool for a supergeek to be caught doing documentation.
- BookSprints.net:I'd seen talk on the web about the great things other people were doing with book sprints.
- Early adopters:BookSprints.net has all the information about book sprints.Anne Gentle was an active and enthusiastic participant in the 2008 book sprint for One Laptop per Child.Adam Hyde writes about the OggTheora book sprint held in Berlin in September 2009. This is one of many book sprints organized by FLOSS Manuals.Atlassian’s first doc sprint happened in February 2010. The focus was on tutorials for software developers.
- More sprinters:Anne Gentle reported on a docsprint held in November 2010 as part of an OpenStack Design Summit.Mozilla is another keen host of doc sprints. Sprinters develop documentation on the MDN wiki for JavaScript, CSS, HTML, and other open web technologies. Janet Swisher is chief organizer.WebPlatform.org is an up-and-coming sprint organiser. They’ve run a number of sprints recently. There are more links in the reference section at the end of this presentation. And we’ll hear some stories from recent sprints soon too.
- Our first doc sprint:So we decided to give it a go. Sprinting FTW!We kicked off our first doc sprint in February 2010.These are the results of the first doc sprint we held:We produced 19 tutorials on how to develop gadgets and add-ons for our products.A few developers decided to spend the first day of the sprint looking over the existing reference documents and doing a mass update, before starting the tutorials.Some even decided doc maintenance was the most valuable exercise for the entire sprint.
- Community:A doc sprint is all about the people.But why do they do it?Why do people give their time so freely and generously?Is it the chocolate?
- Why do people do it?Before you start writing invitations to your doc sprint, it’s useful to know what motivates people to take part. This will help you word your blog posts, email messages and other forms of invitation.Andy Oram has published a useful study at O’Reilly’s OnLamp.com. The study is called “Why do people write free documentation?”If you’re running a doc sprint for your company, it’s not exactly free documentation, but I think the same sort of motivations apply. (Basically, people are just awesome.)People feel good about developing a new tutorial that is as near perfect as their skills can make it.External developers and authors enjoy the contact with your organisation, and employees enjoy and learn from the external developers who are using your tools.People find value in learning from the other experts who are taking part in the sprint.People like helping other people.People get a sense of satisfaction from fixing documentation that is out of date.
- Swapnil:Swapnil was one of the participants in our August 2012 doc sprint. He was not a staff member, nor even a customer. He had never used any of our products.Swapnil wrote the following on his blog, about why he wanted to take part:“Along with the immense challenge it presented personally, this was also a chance to work on a product and a team I’ve never worked on/with before.”Swapnil travelled all the way from Melbourne to Sydney to join us. That’s about 1000 kilometres. He did the journey twice, on two separate days.
- Agile or what?Let’s take a look at how a doc sprint is related to agile development,and what aspects of the agile methodology we can grab to make the doc sprints work.
- What is agile methodology?Agile methodology is a collection of guidelines on how to organize a development team.It’s based on a set of philosophical principles about the best way to produce software systems.The Agile Manifesto was written in 2001, by 17 people.The authors include Ward Cunningham, Martin Fowler, Jeff Sutherland, and other well-known software gurus.http://agilemanifesto.org/Since then, a number of variants of agile methodology have arisen:Extreme Programming (XP)ScrumKanbanAnd many variationsIn fact, no two teams practise the same variant of Agile.That’s at the core of Agile – constantly adapting it to suit your team and improve its purposes.We can make use of that fact in our doc sprints.
- Agile techniques:In a doc sprint, we use the following key aspects of agile methodology:Timeboxing:Work for a set period.Begin with a goal.Re-assess the goal continually.Redefine the goal if necessary, to ensure we achieve something useful within the scope of the sprint.Self-organising teams:The team is central. People collaborate. They examine their work, and continually improve the way they work together.We hold a planning meeting at the beginning of the sprint, and report-back sessions throughout.We hold a retrospective at the end, and use the resulting feedback to improve the next sprint.Efficiency:PreparationPlanningHelping people do their best work during the sprintStructure:TemplatesGuidesMaking sure people know the part they will play
- Sprints in agile methodology:Let’s dive deeper into the concept of a sprint.The sprint is a key part of the agile workflow.A sprint is a period during which the development happens.The period is often two weeks. Sometimes just one week.Each sprint should deliver a potentially shippable product. In other words, something to hand to the customers.Developers hold a planning meeting at the beginning of the sprint. The primary purpose is to break the tasks into chunks that can be finished within the sprint.At the end of each sprint is a retrospective, where team members examine what went well and what could be done better. The output is used to improve the following sprint.
- Planning a doc sprint:A doc sprint takes a lot of planning and hard work up front, then review and tidying up afterwards. But it is worth it because the result is high quality documentation written by experts in the field. Good preparation means that the sprinters get off to a flying start when the day of the sprint dawns.
- When to start:Good advice is to start planning early, two or three months ahead, especially when organizing your first doc sprint.If sprinters will need to travel long distances, or if the sprint is longer than a day, they will need plenty of time to make arrangements.Then swing into full action about two weeks before the sprint. Remind everyone who has already signed upLook for more signeesCheck arrangements for venue, catering, technology, etcClear your own calendar
- Who to invite:Don't be shy. To get your numbers up, you’ll need to invite a large number of people.
- Who to invite:Invite everyone from within the company: developers, support engineers, product marketing, business analysts, and CEOs. As technical writers, we know that everyone has an interest in the documentation. But do they know that? Taking part in a doc sprint is a great way for them to find out.
- Who to invite:Consider inviting people from outside the company too. Community developers, community authors, partners of the organization – all will have useful information to contribute and will in turn benefit from taking part.
- How to invite people:Make it cool. People should feel they’re doing something good, and something that will look good on their resumé.Tweet, blog, send Google+ and Facebook updates. Where possible, send a personal invitation to each sprinter. Let them know why you have chosen them. For example, they may be active in the community, or perhaps they have already contributed to the documentation, or they have a specific skill set that is valuable for this sprint. Personal email invitations are very powerful. One of our external attendees mentioned this specifically during a retrospective session. Send the invitations in good time. If you are planning to invite people to fly in from other cities, two months is a good time frame. For people who are in the same office as you or people who intend to work remotely, one month is enough. After all, how many of us know now whether we will be free to contribute to a doc sprint in two months' time?It is a good idea to have the wish list (which may still be a draft) and the basic information about the doc sprint available online by the time you send out the invitations. Although nothing is yet finalised, suggest that people put their names down next to the tutorials that they would like to develop. This will get their buy-in early on.As the sprint date draws closer, remind people on every channel available. Do whatever it takes to keep the date and the importance of the doc sprint in everyone's mind.
- The coolth factor:How do you make the invitation attractive to a bunch of geeks?This example comes from one of our blog posts inviting people to join us in a doc sprint. It’s hard to read the text on the screen, so let’s take a look at each point in turn.Trivia:Yes, “coolth” actually is a word. It was first used in the mid-16th century but is rarely used before the 20th century. (From the Oxford dictionary.)
- People will do anything for a T-shirt!
- Let people know they will be recognised as the author of the material they contribute.
- Tell them how much the technical writers will appreciate their participation.
- People love learning new tools and technologies.Note that we’re targeting those points from Andy Oram’s study of why people write free documentation.
- The ultimate sweet spot!
- OpenStack sprint:This extract is from Anne Gentle, quoting Adam Hyde at an OpenStack book sprint in March 2013.
- Getting the documents you need:How can you make sure the sprint will produce the documents you need?Define a focus for the sprint. This is something short and simple. For example:Developer tutorials for product X.Quick-start guides for product Y.API documentation for version N of Product Z.Create a wish list of the tutorials or other documents that you would like to develop, and make the wish list publicly available.Create a template for each type of document required. Templates are excellent for providing consistency, and helping people get started. Get rid of that blank page feeling.Consider writing a simple style guide.Write detailed and careful technical guidelines on how to use the documentation platform. If the sprinters will write code as well as documentation, they will need technical guidelines for the coding part too.
- Wish list:Let’s look at the wish list in more detail. This is the most valuable document for defining the scope of the sprint, and ensuring you get what you and the stakeholders want.Here is an example of a wish list.It’s basically a table, with the following columns:Title of the guideSprinter assignedAnother knowledgeable sprinterCommentsConduct a lengthy, asynchronous and free discussion about this wish list.Give the discussion plenty of time.Consult internal and external stakeholders – plumb the audience.Allow everyone to add and update the wish list.Often the would-be sprinters will take an active and interested part in the building of the wish list.Then, near the start date of the sprint, cull and refine the entries to ensure you get what you need.
- More planning:Other things to do before the sprint starts.Configure a documentation development platform that can handle multiple authors. If external sprinters will be taking part, then you may need to make special arrangements to give them access to the platform. A wiki is useful here.Set up a communication plan.Set up the development environment including: any software development kits required, a source repository, and a build server.Set up and give people access to an online chat room, video conferencing facilities, webinars (web-based meetings), and an email group.Organize the facilities at the sprint venue: a room, network hub and cables, extra power points, and notices to tell people where to go.Organize the catering. It saves time if you have lunch delivered. Chocolate is inevitable.Publish the schedule and details of the online facilities and the venue.
- Hot tip:If I could give only one tip, it would be this:Get other people involved as soon as you can. Right at the start of your planning.People are awesome. Give them an idea and a bit of a framework, and they’ll start contributing their ideas and help with gusto.Involve your team, stakeholders, external people, the world.It’s better to have to trim and prune ideas than to scrabble in the dust for them.
- Sprinting:Let’s talk about running the sprint itself. What happens, and how to get the best out of the sprinters.
- Global sprinting:In our 4 doc sprints, we’ve had people from round the world. Some take part remotely. Others travel long distances to join us.
- How to sprint around the world?How can we manage the fact that the sprinters are in different locations, different time zones, and are sometimes even not be native English speakers?
- How to sprint around the world?How can we manage the fact that the sprinters are in different locations, different time zones, and are sometimes even not be native English speakers?These are your key tools:Flexibility. Be prepared to bend your plans to suit people.Schedule. Make sure people know what’s happening when.Mentoring. Include people on the sprint whose main task is to help other people. The print gurus.Technology. It’s your friend. In a later section we’ll look at the tools in detail.
- Macro tekkie:It’s time for some stories.Ellis Pratt, of Cherryleaf, volunteered to write the “how to” guides for a couple of Confluence macros he had written.http://www.cherryleaf.comHe would be away during the actual dates of the doc sprint.So we “bent” the rules and allowed an early sprint just for him.This is a great example of flexibility.You can bend the rules of a sprint, to ensure you get what you need.Some people may want to start work a couple of days before the sprint starts.Others may need to start after the sprint ends.Go with the flow.
- Remote in Russia:One of our sprints focused on task-based user guides.Why?We knew our documentation lacked this sort of guide.We wanted to give customers and stakeholders an opportunity to show us what they wanted.Every doc sprint is different. The characteristic of this one is the number of guides that we developed collaboratively: many authors working on one page, sometimes together and sometimes asynchronously.An example is the guide to developing technical documentation on a wiki.Those of us in Sydney worked on a page during our daytime. Overnight, Katya in Russia, and others in various locations, reviewed the work and gave us feedback.Katya is a technical writer who uses the product that our guides were describing.
- Alone in Amsterdam:Andreas is a developer of add-ons, from a software company called aevolu. Andreas was keen to take part in an Atlassian event, to meet people and learn about the development frameworks.For the sprint, he travelled all the way from northern Germany (near Denmark), to our office in Amsterdam.We were in Sydney. We communicated via video conferencing in our evenings, his mornings.He looked a little lonely whenever we saw him, because it was very early morning there. He assured us that the people in the office treated him well and fed him chocolate!
- Sprint schedule:Especially when you have people scattered all over the show, it’s essential to have a carefully constructed and well documented schedule.People need to know when they can find each other online, and when the general get-togethers will happen.This is what worked for us. There are plenty of variations. Use this as a starting point, and adapt it as your plans take shape.I’ll run through the main items in the schedule, then we’ll look at them in more detail.On the first day, we held a kick-off meeting. We scheduled it at a time when Sydney and San Francisco were online. So we had video-conferencing for the two offices, and a webinar running simultaneously for the remote sprinters.We repeated the kick-off meeting in the Sydney evening, to pick up the sprinters inn Europe. Andreas was there on the VC, and others joined us in the webinar.Every day, we held a report-back session, which we called a standup, and a teaching session. And of course, people did the document development and had some fun.On the last day, we had a catered lunch, presentations, and the sprint retrospective.
- Example schedule – last day of the sprint:This is an example of what the last day might look like.Get them started early!Now let’s take a look at some of the sprint events in more detail.
- Kick-off meeting:We start the sprint with a kick-off meeting.The aim is to get as many people as possible together in the same room.Others join via webinar and videoconferencing.If necessary, we hold two kick-off meetings, to cater for people in weird time zones.This is a great time to welcome everyone and help everyone get to know each other. Start with a quick welcome, then go round the table asking everyone to introduce themselves. Keep it short. Suggest people tell everyone just the following:Their nameThe organisation they work for, and their roleArea of expertiseThe tutorial they plan to tackleThen give everyone the essential information they need to know:Where to find the templates and technical guidelinesWhere to find the schedule, and what they can expect to happen nextA quick introduction to the wiki or other collaboration platform, and the technical environmentEnd with a call to action, and a promise of fun stuff to come.
- Daily standup:A “standup” is a stalwart tool of Agile methodology. It’s a short meeting, held standing up. Participants tell:What they did yesterdayWhat they plan to do todayAny problems they’re encounteringIf someone else in the standup knows of a solution, or is encountering the same problem, that person will shout out, and the two will get together after the standup.In a doc sprint, this has proved very useful indeed.We can also be flexible, especially with different time zones and locations. Use the technology at our disposal. And hold the meeting sitting down if that’s easier.
- Teaching sessions:People are here to work. But they’re often here to learn too. And some of them may need a teaching session in order to do the work of the sprint.This is something that arose from feedback given in the retrospective during a previous sprint. During our most recent sprint, we ran a few short educational sessions every day. Each session lasted just ten minutes. The technical writers ran some of them, and an engineer ran others. The sessions covered the structure of the documentation, documentation techniques such as content re-use, templates, the source repository, and best practices for writing tutorials. These sessions were well received, and were also a useful launching point for further discussion.It’s all about getting the best out of sprinters, and giving them something in return.
- Fun and coolth:Be cool.Make your doc sprint something people can Tweet about with pride.A theme is great for making a doc sprint sound like funA theme gives the sprinters a sense of unity.It helps with mundane but important things like prettying up the wiki pages and blog posts.We agonised for a number of days about choosing the theme for our first doc sprint. What could it be? Something to do with the Hitchhiker’s Guide to the Galaxy? A sports car or running theme, to fit with the word “sprint”? The one and only theme occurred to me in that most inspirational of places — the E66 bus on my way home one evening: Chocolate, of course!Once you have the theme, it’s easy to think up other fun things:A haiku competition. The haiku topic is of course your theme.We also had online crosswords and other word games. They weren’t as popular as the haiku, perhaps because we offered a prize for the winning haiku.On one of our doc sprints, we hid a ticket from Charlie and the Chocolate Factory in a couple of places in the documentation. People who found the winning tickets got a funny hat!It’s also a good idea to offer people a catered lunch on one of the days, and to have pizza for those working late.
- Presentations:On the last afternoon of the sprint, we hold a presentation session, also known as “show and tell”.Having a deadline like this is a great motivator for the sprinters. It gives everyone something to work towards, and finishes the sprint with a bang.Keep the presentation session short and simple: Each person has 3 minutes to walk through their tutorial, explaining its purpose and its cool flashy parts.Just before the presentation session on our first sprint, I overheard this affectionately ironic exchange between two developers walking into the room:"This is the doc sprint presentations, right?""Yes, mate. We're going to talk about documentation for the next two hours. It's going to be awesome!"
- Retrospective:A retrospective is a useful tool that we’ve picked up from Agile methodology.The aim is to get feedback and suggestions from attendees, so we can keep improving the way we run doc sprints.The format of a retrospective is to ask people:What went wellWhat could have gone betterIt’s especially interesting holding a retrospective when your sprinters are scattered around the world. How did we do that?In Sydney and San Francisco, we met with all sprinters immediately after the presentations, to go through their feedback in detail. Then we used a retrospective page on the wiki to gather comments from all attendees scattered across the globe, and to collate all the feedback from the live sessions.Again, it’s all about the people. The sprinters are your best source of information about how to run a doc sprint.
- Retrospective results:Let’s take a look at the feedback from our very first doc sprint retrospective.As we go through these items, you’ll notice that we took the feedback to heart. This presentation has shown that we’ve acted on the feedback items in subsequent sprints.What went well:Teamwork: This was the most popular item of feedback given in both the Sydney and San Francisco retrospectives.Having the developers and technical writers working together and spending a solid period of time working towards a common goal. Many attendees (developers and technical writers alike) said they learned a lot from the experience too.Co-location:We flew some people over from San Francisco to Sydney for the event, so they could work hand-in-hand with the product engineers. People loved this.Pairing:Some people paired up throughout Doc Sprint, which really helped to increasethe learning experience.Organisation:Feedback was very positive overall, and people felt that the doc sprint was a great success. They suggested we repeat the exercise often and regularly.The schedule was very helpful, especially for attendees outside of Sydney.Duration:People felt that 3 days was the appropriate length of time for a doc sprint.What could have gone better?Doc maintenance:People suggested we do a sprint or two that focuses on doc maintenance rather than production of new material.Templates:People appreciated the templates we had, but suggested some improvementsMore teaching:Some sprinters would have liked more focused teaching sessions during the sprint, rather than impromptu get-togethers with the experts. More promotion:Doc sprints are great, in so many ways. The developers felt that we should shout out on the rooftops when planning one!More pairing...
- Yes, more pairing!People suggested that we encourage pairing more. “The more pairing we do, the greater the shared learning!”
- Aftermath:We want the results of the sprint to sing out to all stakeholders, both internal and external, “Come read this brand new shiny guide. It’s just what you need.”
- Review and publication:Every new document, and every document that’s received a major update, needs to go through a technical review before we publish it.In some cases, just a technical writer review is enough. In others, a product engineer must review the tutorial for technical accuracy and efficiency.Tips:Don’t be too picky. Get the stuff out there as fast as possible, provided it’s technically correct.As always, remember the audience. If you’re dealing with savvy developers, then often something is better than nothing. It points them in the right direction.Do as much of the technical review as possible during the sprint itself. Developers disperse after the sprint. They’re out of the time box. It will be hard to get any of their time after the sprint.
- Thanks and blogs:Sprinters have given valuable time and expertise. Some of the rewards are inherent in the doc sprint itself, such as learning cool stuff from the other experts, having contact with external and internal developers, helping others, and developing a satisfyingly perfect tutorial. Even so, it’s enjoyable and nice to recognise people’s contributions.Write blog posts, tweet about the sprint and the people, send them T-shirts and chocolate if your budget allows.A “hall of fame” is a nice touch. It’s a page that lists the people who took part, with photos if they’ve given you permission. The hall of fame can also include fun things like the winner of the haiku competition.If you don’t blog about it, it didn’t happen.
- Tools:One of the great things about attending a doc sprint is getting exposure to new tools. In this section, we’ll take a quick look at what we used. For more details, follow the links at the end of the slide deck and in the proceedings paper.
- Collaborative writing:We used a wiki: ConfluenceEssential features: Multiple authors working on a documentation set.Ease of use.Notification of updates.Commenting or other way of reviewing content.Configurable permissions. Ensure people have the necessary access. Do this before the sprint starts, if possible.Other tools may be:Another wiki, such as MediaWikiA CMSBookiMicrosoft Office? It’s been a while since I used Office. With its new online, centralised collaboration it may make a good tool. Does anyone know the answer to that?
- Chat:An online chat room essential. Even if you’re all in the same location, it’s useful to be able to chat quietly, post links, and share ideas or questions with the whole group. People can hop in and out as it suits them.For our first couple of sprints, we set up an online chat room using Tea Party, which we accessed primarily through Google Talk.Some people found Google Talk annoying, and said they would prefer an IRC or Jabber conference.For our later sprints, we swapped to HipChat. Most people seemed happy with this.A useful feature of HipChat is that you can see the chat history, even if you were not present at the time.
- Mailing list:We used a Google Group. It worked OK for before and after the sprint. During the sprint, people used the chat room exclusively. Also, we found that not everyone signed up. Our intention had been to use this as a means of communicating with everyone. But that didn’t work. We still had to build our own private mailing list. So I’d say Google Groups isn’t a necessary part of your plan.
- Webinar and video conferencing:A webinar is an online seminar. Typically, people dial in via their PCs. They can hear the presenter and see a shared screen. They can participate by speaking and/or typing comments into a text box. There is no video, just the shared screen.A webinar is useful when you have remote participants, who cannot come to one of the central locations and therefore cannot participate in person or via a video conference.We used GoToWebinar.A video conference is useful if you have one or two central locations, hooked up via VC.We used both a video conference and a webinar, running at the same time, for:Kick-off meeting at start of sprintDaily standupsPresentations at end of sprintRetrospective
- Code repository:It’s very very cool to learn and use a DVCS – Distributed Version Control System, like Git or Mercurial.We used Bitbucket and Git.An alternative is GitHub.
- Extending the metaphor:As technical communicators, we can employ some neat agile tricks to get what we need from our stakeholders and subject matter experts.Let’s take a quick look at some other innovative types of sprints.
- Innovation sprints:Technical writers are busy people. Where can we find the time to think about innovative techniques or procedures in our technical writing and documentation? And once we have some ideas, how do we find the time to put them into practice?That’s where an innovation sprint comes in. It’s a day (or more, if you’re very very lucky) when the technical writers stop doing their day job, put their thinking caps on, and do something different.Planning:Start an innovation register – a list of ideas for improving processes or the documentation.Set a date for the innovation sprintA couple of weeks before the date, have a huddle around the innovation register and start deciding what each person will be doing during the sprint. Grab ideas from the innovation register.On innovation sprint day:All writers devote the entire day to their innovation project.We wear funny hats! We wanted a tactful way of letting people know that the technical writers were otherwise engaged for a day. It works. And it’s funny. Afterwards:Schedule a couple of hours for presentations – “show and tell”.Decide which of the ideas we can implement.Show them to stakeholders, and implement them.
- Doc blitz-tests:Our Quality Assurance team first introduced blitz tests, to test the applications themselves rather than the documentation. In a blitz test, people from various disciplines spend an hour doing concerted and concentrated testing of specific aspects of the product. It’s a way oftimeboxingthe testing. It’s also a way of viewing the product as whole rather than the disparate bits that have previously been reviewed individually. Best of all, it’s a way of working together on improving the product.We decided to try it out on the documentation too.The developers, QA engineers, product managers and various other people join the technical writers for an hour, working together to test the documentation due for imminent release.Preparation and tools:Test planKick-off meetingWiki or other tool for collaborative editing of the documentationChat room for quick reporting and discussion of problems foundIssue tracker for reporting problems found
- Feedback from blitz-test:After the blitz test was over, I asked the development team what they thought of the experiment. Here’s their feedback about why they thought it was beneficial:It generated a feeling that the entire team has a responsibility for the documentation.It built a feeling of team spirit amongst the members of the team: developers, QA, writers.It gave us the obvious verification that what we’ve specified in the docs is correct.It can be worthwhile double-checking the docs in case functionality or edge cases are missed in the docs (because we may have subtly changed the implementation without notifying the tech writers).We found bugs in the application, because we were running through processes in the way an end-user would.
- Doc blitzes:A documentation blitz is similar to a blitz test.Instead of looking for problems, the idea of a documentation blitz is to fix a specific and large-scale problem. The participants may be the technical writers and the development team. Let's say the development team makes one of those small, dreaded changes to the product that necessitates sweeping changes to the documentation. Almost all pages and screenshots are affected. A small technical writing team will find it hard to apply the updates in the time allowed. On the other hand, the changes are fairly straightforward and follow an easily defined pattern. Just the job for an engineer! Edwin Dawson has written a blog post about such a documentation blitz, held at Atlassian.The story behind the blitz? Fairly late in the release cycle, the development team changed the administration user interface of JIRA, the issue tracking software that Atlassian develops. The UI changes were high level and significant, and they affected many pages in the JIRA administration guide, including all the screenshots. The engineers realized that this would put a heavy load on the technical writers, so they offered to help with the updates.Preparation:A plan that specifies the pages that need updating, the changes required, and the date, time, and location of the blitz. Collaboration tool Screenshot capture tool.Results:People who took part in the blitz reported that they enjoyed it and felt a sense of achievement and an increased team spirit.The engineering team took ownership of the required documentation updates.The engineers saw at first hand how changes in the product require updates to the documentation. In future releases, they will know when to alert the technical writers of documentation-breaking changes.Engineers became more aware of the work that technical writers do. A couple of the doc blitz participants came up with the idea of automating the screenshot updates in future releases.The time-critical updates were done in time, without technical writer burnout.
- More stories and tips:To finish off, let’s look at some stories and tips from doc sprint experts around the world.
- Knock knock:Anne Gentle pointed out a strange story, from a FLOSS Manuals sprint:http://en.flossmanuals.net/collaborative-futures/ch046_knock-knock/Someone arrived unexpectedly to take part in the sprint.... “He didn't even say his name, he just said he had some ideas about collaboration and he really wanted to contribute”The team was unprepared for this eventuality.They didn’t have the infrastructure set up to make it possible for him to contribute.The resolution: They arranged for him to contribute remotely, starting the next day.The lesson: Be prepared for anything to happen at your doc sprint!
- Doc Sprint Dashboard from WPDS:Jay Meissner has published a comprehensive report about the first ever WebPlatform.org Doc Sprint in Berlin, in February 2013.They’ve introduced a great idea: A doc sprint dashboard, which they’ve made available to all of us on GitHub: the "Web Platform Doc Sprint Dashboard“:https://github.com/webplatform/DocSprintDashboardI recommend Jay’s report as a great read. Perhaps as a result of the dashboard, there are plenty of stats about the sprint, as well as very useful information to be gleaned from the links and feedback.http://lists.w3.org/Archives/Public/public-webplatform/2013Feb/0120.html
- Tips from Peter Lubbers:Peter Lubbers, HTML5 enthusiast, has organised a few doc sprints at WebPlatform.Org, in collaboration with Google.https://twitter.com/peterlubbers Peter Lubbers and Jay Meissner have started work on a "Doc Sprint in a Box" page that will have plenty of tips. Keep an eye open for it.Peter’s tips for people wanting to run a doc sprint:Get some prizes (get a company to sponsor a raffle prize for which people will stay a few extra hours). Make sure people are fed and watered--they are putting a lot of volunteer time. Have some cool swag items.Peter’s tips for people wanting to attend a doc sprint:Just go, even if it is just for a few hours. If you're in the Bay Area, sign up for the SFHTML5meetup– we often organize sprints.
- Anti-troll measures deployed:A cool blog called “Notes from the mousepad” reports on GNOME doc hackfests. In one post, the author tells the story of someone who showed up and promised to troll the sprint.Then they got to talking, and the troll was converted to a fan.“one person even showed up to say, “Oh, you are working on GNOME! I don’t like GNOME 3, let me troll you.” They initially starting out trolling, but then we got to talking about the new Legacy session in GNOME 3.8 – and they are interested! Face-to-face interaction win.Aside from the initial need to deploy anti-troll measures, it was a successful event.”http://j1m.net/2012/12/28/chicagoans-and-gnome-part-3/
- References:Here follow a number of slides with links to blog posts and articles. Please also check the earlier slides in the presentation. Some of them have additional links.
- TO DO