For the past year I’ve been working with colleagues to create and run Google’s Season of Docs program. It’s super exciting that the first results are now out. There are more results to come in the new year, when the long-running projects finish.
Congratulations to the technical writers and open source mentors who’ve successfully completed their standard-length projects and good luck to those who’re working on the long-running projects. Also a big thank you from me, to everyone who’s taken part in this pilot of the program, including those who had to withdraw from the program for various reasons. It’s been a privilege to receive all the feedback from everyone involved and to learn from the experiences of so many people.
Results for Season of Docs 2019
This year’s Season of Docs included a limited number of technical writing projects, as a pilot to measure how well the program would be received. There are 36 successfully completed projects out of the 41 standard-length projects that finished in December 2019. Eight long-running projects are still in progress, scheduled to finish in February 2020.
The goals of Season of Docs are:
- Bring technical writers and open source projects together to improve open source documentation and thus to contribute to the excellence of open source products.
- Give technical writers around the world the opportunity to work in open source and to learn about open source processes, tools, products, and code.
- Help open source projects understand how technical writers work and what technical writers can contribute to the open source projects.
- Improve the overall experience of contributing to open source, by providing excellent documentation for new contributors.
Season of Docs 2019 participants come from round the world, including all continents except Antarctica.
What are the participants saying about their experiences so far? Here are a few quotations from the blog posts and reports that people have published.
- From technical writer Kartik in a blog post, Experience in Google Season of Docs 2019 with Apache Airflow:
I also started getting invited in the PR reviews of other developers. I am looking forward to more contributions to the project in the coming year.
- From technical writer Elena in the project report, Apache Airflow: Documenting using local development environments:
I’m deeply grateful to my mentor and Airflow developers for their feedback, patience and help while I was breaking through new challenges (I’ve never worked on an open source project before), and for their support of all my ideas! I think a key success factor for any contributor is a responsive, supportive and motivated team, and I was lucky to join such a team for 3 months.
- From technical writer Aaron, quoted in a blog post by open source mentor Olivier Hallot, The LibreOffice Documentation Team Announces the LibreOffice Online Guide:
My experience working on this guide was fantastic, and I would urge anyone interested in getting involved with open source to consider documentation as a first step. The Document Foundation’s documentation team in particular has a very well-established process and infrastructure for producing their products, and one of the only things I can think of that would help them is more volunteers.
- From technical writer Shaloo in a blog post about the GenPipes project, Giving it your all to Documentation!
Unfortunately, most of us who write software, think that documentation means simply translating what the software does in plain English. That is so not true. Documentation is more to do with how to use your cool software and solve real life pain points. Staying in touch with your user needs is of paramount importance, whether it is code that you are writing or the documentation for using the same.
- From technical writer Laurel in a post on the Ensembl blog, Ensembl is part of the first Google Season of Docs!
It has been both fun and interesting to learn about the Ensembl REST API implementation as well as to learn about what people who use the REST API need to get started.
A brand new tutorial is now available for GDevelop, and we would like to thank @end3r for writing it as part of Google #SeasonOfDocs!
Thanks a lot to @felicity_brand for supporting the #OSGeoLive project in #SeasonsofDocs 2019. She did a great job and improved our @osgeolive documentation a lot.
- From technical writer Edidiong in the project report, Modernize (rewrite) the VLC user documentation:
Overall, It was one of the best things that happened to me this year. I have been using VLC for as long as I can remember and the fact that I was able to contribute to the organization is an honor.
- From technical writer Pavithra in the blog post, My GSoD Journey – Part 3:
I like working with the Wikimedia community. I got to interact with some really amazing folks and the overall experience has been wonderful! Even though Season of Docs has officially come to an end, I intend to continue contributing and would welcome interested folks to join us.
- From technical writer Mister Gold in the project writeup, Report for the Bot Docs project:
At the end of the GSoD program, my Rocket.Chat mentors asked me to review a technical writer job posting they’d created. They said that the contribution I made to Rocket.Chat is invaluable and cannot be underestimated. They were so excited and impressed by this project that they have decided to hire a person who will be in charge of all the qualitative documentation updates. Rocket.Chat team confirmed that this is one of the greatest achievements of all the times in Rocket.Chat thanks to my work.
- From technical writer Muhammad in the project report, OpenMRS: Write Code, Save lives!
GSoD not only provided me with an opportunity to learn about open source but also to interact with some of the most wonderful people around the globe working enthusiastically for betterment of society and help create and most importantly maintain a Medical Record System completely free of cost for under-privileged as well as other users.
GSoD not only increased my knowledge about open-source and led me to meet exciting people, it also helped me to further enhance my technical writing and managerial skills…
I would love to continue working for OpenMRS and be an active member of the community.
- From technical writer Areesha in a writeup of the project, OpenELIS documentation for end users:
Google Season of Docs introduced me to open-source community. I realized how open-source projects offer multiple benefits to its users. Open-source systems provide more flexibility, security and transparency to the users as the system is continuously being reviewed and updated…
Writing technical documentation for a system that is implemented at such a wide scale and is a part of a global community made me learn so much about how the technical documentation is done in the real-world at the corporate and professional level.
- From technical writer Anna in a writeup of the project, How did Open Collective’s docs change in three months?
This community has welcomed me with open arms and I couldn’t be more grateful for that. Open Collective has found in me a contributor for life, and I hope to keep contributing for as long as I can.
- From technical writer Anne in the project writeup, The Ultimate Beginner’s Guide to NumPy:
If you’re interested in getting involved with NumPy or Google Season of Docs, I highly recommend it. If you’re new to open source projects, you might have a bit of a learning curve setting up your workstation, becoming familiar with NumPy’s contribution guidelines, and getting to know the ins and outs of .rst and Sphinx, but it’s so worth it. It’s definitely challenging if you haven’t done it before, but keep going. Once you get those details nailed down, you can start having real fun!
- From technical writer Alex in a writeup of the project with International Neuroinformatics Coordinating Facility (INCF), Technical Writer, Google Season of Docs 2019:
I’M STILL SMILING!
It’s well worth taking a look at all the project reports listed on the Season of Docs website, to see the scope of the projects tackled, the challenges that the technical writers faced, and how they overcame them. Every story is different!
Please do let me know of any posts I’ve missed, or if you’d like to add any experiences of your own. Add a comment on this post so that others can read it too.
Opportunities to contribute to open source
If you’re looking for opportunities to contribute to open source, these opportunities abound.
A note to avoid potential confusion: Contributing to these projects would be outside of the Season of Docs program, unless you’re already officially signed up to take part in the relevant long-running project in Season of Docs 2019, or you’re accepted into a future Season of Docs program in 2020 or beyond.
Some suggestions for finding a project to contribute to:
- In their project reports listed on the Season of Docs website, many of the technical writers describe followup work to be done.
- The open source organisations published detailed lists of ideas in their original proposals for Season of Docs. Many of these ideas are not yet addressed, because Season of Docs is only three months’ worth of writing!
There are more Season of Docs 2019 results to come
To the technical writers and mentors working on the long-running projects for Season of Docs 2019: Have fun, best of luck with your projects, and I’m very much looking forward to seeing the results in February!
To add to the celebratory nature of this post, here’s a picture of a tea tree flower spray which I came across while walking in the Australian bush:
Are you coming to the Write the Docs Australia 2019 conference on 14-15 November in Sydney? You’re invited to join us in a two-hour doc fixit on Thursday afternoon, as part of the conference.
Become a contributor to an open source project, learn a bit about how open source works, and help improve the experience of Kubeflow users. All in just two hours!
During the fixit, you’ll add a touch of tech writer shine to the Kubeflow docs. Docs are a super important part of the user experience of any product. Typos and grammatical inconsistencies can spoil that UX. Yet typos and odd syntax creep into any doc set so easily, especially when the doc set is largely written by non tech writers. You can help us set things right.
Where and when
The doc fixit is part of the Write the Docs Australia 2019 conference.
- Date and time: Thursday, 14 November, at 1pm.
- Location: Water Police Court, Sydney.
You don’t need to register separately for the doc fixit. Just register for the conference, then come along to the fixit on Thursday.
Your friendly doc fixit helpers
The doc fixit hosts are:
- Sarah Maddox (that’s me: Kubeflow tech writer at Google)
- Alec Glassford (Tech writer at Google)
- Riona MacNamara (Tech writer manager at Google)
What happens at the fixit
Here’s how the fixit will work:
- Before the fixit, I’ll create a spreadsheet with a list of doc bugs that need fixing. They’ll mostly be small things: typos, consistency in page structure, capitalisation, and so on.
- At the start of the fixit, I’ll give a very short talk introducing the product (Kubeflow) and open source.
- Then the group will look at the list of bugs and each person will choose what they want to do.
- My assistants and I will help people create GitHub IDs if necessary.
- Each person will create an issue in the GitHub issue tracker, describing the bug they’re about to fix.
- Each person will then update the relevant doc on GitHub and send a pull request (PR) for review.
- My assistants and I will help people sign the contributor licence agreement if necessary. (A bot will prompt them to do this when they send their first PR.)
- My assistants and I will review the pull requests and approve each one when it’s ready.
- The continuous merge/publish tools on the GitHub project will merge the change and publish the update in the docs.
- The contributor will see their update appear in the docs!
I’ll also prepare a guide to for fixit participants, with the basics on how to work in GitHub and how to update the Kubeflow docs. The guides, in combination with the three of us helping during the fixit, should make the fixit fun and a useful learning experience for everyone.
Here’s how you can prepare for the Kubeflow doc fixit:
- Bring a laptop with WiFi capabilities.
- If you don’t already have a GitHub account, sign up for one. If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
- Sign the Google Contributor License Agreement (CLA). If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
- It’s not mandatory to do any prework, but it will help if you know some Markdown.
Last week I ran the Kubeflow Doc Sprint, an event which brought open source contributors together from all corners of the world to write docs and build samples. We worked in groups and individually, chatting over video conference and on Slack, collaborating via online reviews and comments. We tackled complex technology which for some of us was entirely new. We learned a lot and achieved a lot.
Planning a large doc sprint may seem like a daunting task. Actually, it’s a large set of not-too-daunting tasks. The daunting bits are (a) knowing what the necessary tasks are, and (b) getting organised to complete the tasks. If you’re considering running a doc sprint, I hope this blog post gives you some useful pointers.
A bit about the Kubeflow Doc Sprint
A doc sprint is an event where people get together to write documentation. The time frame can be anything from a few hours to a few days. From past experience, I’ve found that three days is a good period to aim for. It gives people time to contribute a fairly sizable piece of work and to enjoy the experience of the sprint.
The Kubeflow Doc Sprint ran from 10-12 July. We had contributors working in groups in Kirkland, Sunnyvale, and Chicago, as well as individuals online all over the world. We produced around 35 pull requests. A pull request is a set of changes that related to a given goal. For example, one pull request may add a new document or update related content in a number of documents.
My post on the Kubeflow blog includes a list of the tutorials and samples we built during the doc sprint. The blog post also has some pictures of the people in the sprint.
Optional extra: Learning on the sprint
We decided to run some short, targeted presentations during the doc sprint, focusing on documentation best practices and UX. I’d had feedback from previous doc sprints that three days is a long time to be heads down writing docs. People need a bit of variety, and they like learning new patterns that are at least tangentially related to their day job.
These are the mini talks from our doc sprint:
- How to address the reader in technical documentation.
- Passive resistance.
- A short guide to writing well.
- Kubeflow: A First Impression.
- Guiding users through a journey.
The tasks involved in planning and running a doc sprint
Here’s a brain dump of the things that need doing. But every doc sprint is different. My top hint, before diving into the details, is this: Make a list. 🙂 Add all tasks to the list, big and small, as soon as they occur to you. Start with the tasks from this blog post – pick the ones that apply to your situation. Then add your own.
I used a spreadsheet to track the tasks for this doc sprint, but any tool will do, provided you can share the list with others, set priorities, and make comments on the tasks. And of course, you must be able to mark a task as complete. Ticking off a TODO is one of the best feelings in the world. Your task list from your first sprint will be useful for planning your next sprint.
Preparations two to three months before the event
Start planning early:
- Get budget approval, and check that your manager and team are happy with the idea of devoting time to the sprint.
- Set the dates. Make sure the dates don’t clash with other related events or with holiday seasons. Avoid any important product release dates, if you can.
- Book a venue. First, you’ll need to estimate the number of attendees you can expect. Be generous – it’s far better to have room to spread out than to be cramped.
- Decide whether your budget provides for swag (T-shirts!) and prizes. If it does, organise the vendor and any designs you need.
- Invite people to the sprint. I used a Google Form, which handily put the registrations into a spreadsheet for me.
- Generate enthusiasm and discussion. Make sure people know you are committed to the sprint. That will give them the confidence they need to go ahead with travel arrangements and setting aside time to work on the sprint.
- Order refreshments and meals, if your budget extends that far.
- Arrange additional power extensions and cables, so that people can charge their laptops.
- Start preparing a wish list of docs to write and samples to build. I started the wish list in a spreadsheet, then moved it to the project’s issue tracker to form the sprint backlog. Discuss the wish list / backlog repeatedly with your team and the wider community. Encourage them to add to the wish list.
- Prepare and share an agenda.
Style guide, templates, and sprinter’s guide
It often surprises me that people are so interested in style guides. As a technical writer, I know the value of style guides, but I have a sneaking feeling that other people find them tiresome. Not so! In a doc sprint in particular, people appreciate the guidance. It’s also useful for reviewers to have somewhere to point contributors at, rather than needing to repeat the same style corrections in every review.
People also need to know how to work during the sprint: prerequisites and setup, where the docs are, where the doc source is, how to preview their changes, and so on. Here’s an example of a sprinter’s guide.
Online communication channels
Communication during the sprint is key, particularly when your sprinters are distributed around the globe.
- Set up a video conference call at least twice each day on each day of the sprint, where people can talk about their progress, check whether their work may overlap with someone else’s work, and ask for help on blockers. Useful video conferencing apps include Google Hangouts, Zoom, and more.
- Have an online chat room going. We used a Slack channel dedicated to the doc sprint, in the existing Kubeflow Slack workspace.
- Use a collaborative online tool for reviewing contributions and for tracking work done. We used GitHub’s pull requests (a pull request is a collection of changes related to a particular goal) and issue tracker. Take a look at the Kubeflow documentation pull requests and issues in our GitHub repository.
- Encourage people to add detailed comments to their pull requests, reviews, and issues.
At the venue
It’s often easy to forget the practical things, yet for the participants these are key to feeling welcome and safe:
- Post signs showing people where to go. Cover all the important destinations: the room where the doc sprint is happening; the bathrooms; the exit; coffee.
- If participants have to sign in to the building or if they may have trouble finding the room, have two or more helpers who can escort your guests to the room.
- In your opening speech, tell people the essentials: where to find the bathrooms; whether food is catered or not; who to contact if they encounter difficulties; the agenda.
It’s a good idea to arrange a demo session at the end of the sprint. Give the participants the opportunity to showcase their work and to let you know whether they plan to finish off their work in the days following the sprint.
A demo session can be quite simple. Provide a doc where people can add links to their work. Devote the last two hours of the sprint to the demo session. Display each person’s work in turn, and ask the person to give a three-minute overview, something like this:
- Introduce yourself.
- State the goal of your doc in one sentence.
- Give a short overview of the content.
- Describe any problems you encountered.
It doesn’t matter if only a few people are ready to present a demo by the end of the sprint. The demo session gives a focus and a sense of excitement to the event. In particular, it lends momentum to the last day which might otherwise fizzle out. You can take a look at the sprint demos for the Kubeflow Doc Sprint.
Docs, or it didn’t happen! Write a report and/or a blog post describing the results your doc sprint. Tweet about it. Let people know it was a success, so that they’ll be keen to participate next time. Be sure to list the achievements of the sprinters. They’ve devoted time and effort to the sprint. For many of them, the results you publish will be useful in their performance reports.
If you promised T-shirts or other swag, remember to send them out to the participants.
Don’t assume people know something, even though you’ve already told them via email and in chat and in person… During an event, people get overwhelmed with information and noise and meeting new people and trying to understand new things.
So, tell people the most important things again and again, in multiple channels.
One of those most important things to tell people is where to find all the information they need. For our doc sprint, the source of truth was the Kubeflow Doc Sprint wiki.
I’ve written a few posts about doc sprints and doc fixits over the years. Skimming through the posts shows just how different each doc sprint is!
Do you have any hints you’d like to share?
Many people have run open source doc sprints. If you have any hints or links, please feel free to add them as comments on this post.
Technical writers around the world can now explore the open source organizations taking part in Google’s Season of Docs program. It’s time to start preparing your project proposal!
Season of Docs provides a framework for open source projects and technical writers to work together on the projects’ documentation. It’s a program run by Google in collaboration with participating open source organizations.
The program kicked off in March 2019 by inviting open source organizations to apply to take part.
The list of participating open source organizations is now available on the website.
The next step is for technical writers to apply to take part in the program.
Explore the tech writing project ideas and contact the organizations
It’s exciting to see the variety of open source organizations taking part, and the technical writing project ideas that each organization has on on offer!
If you’re interested in working on open source docs as part of the Season of Docs program, now’s the time to start planning your project proposal. You can contact the organization(s) that you’re interested in right away, and discuss your proposal with them. Talking up front is a great way to ensure you submit the best project proposal that you can. Then you’ll be ready when the technical writer application phase opens on May 29.
Some hints from me
Each open source organization has published a list of ideas for technical writing projects they’d like to complete within the Season of Docs program. (Follow the links from the page of participating open source organizations to see each organization’s project ideas.)
- Remember that you’re the one with technical writing expertise. Write your proposal based on your experience of other projects. Include your plan for design and execution of the project, and scope the project so that it’s achievable within the Season of Docs time frame.
- You can split an organization’s idea into smaller chunks and write a proposal for one or more of those chunks.
- You can also propose an entirely new project idea of your own, based on your exploration of the organization’s open source product and existing docs.
- Read the Season of Docs FAQ and technical writer guide for information on how much time you can expect to spend on a project, and about long-running versus standard-length projects.
- Do get in touch with one or more organizations to talk about the projects they have on offer. They’ll be able to help you design a proposal that you can then submit to Season of Docs. It’s the organizations who’ll eventually choose the technical writers to work on their docs during the program.
- You can talk to as many organizations as you like, and you can submit more than one application to Season of Docs, though only one application will be accepted.
- Your project proposal forms part of your application to Season of Docs. Read the technical writer guide and application hints for help with creating your application.
- Make your project proposal count. There may quite possibly be other technical writers proposing to the same organization.
Questions and discussions
Here are a few places where you can learn more and ask questions:
- Join us on the Season of Docs Slack workspace or discussion mailing list, anytime. For information on how to join, check out the page about discussion channels on the Season of Docs website.
- Will you be at STC Summit in Denver on May 6-8 (next week)? I’ll be speaking on Tuesday, May 7, at 2pm about open source, documentation, and Season of Docs. See the session description in the summit app (you need to be logged in). You can also grab me for a chat in the conference hallways.
- Join the Write the Docs online meetup in mid May. Write the Docs Australia and Write the Docs India are hosting a joint online meetup (webinar) on May 15 (APAC time zone). Join us for an overview of Season of Docs! The webinar is free of charge and is open to anyone interested.
Hope to see you in one of those places. 🙂
Last week Google announced a new program, Season of Docs (g.co/seasonofdocs). The program provides a framework for technical writers and open source organizations to work together on a specific documentation project chosen by the open source organization and the tech writer concerned. From April 2, interested open source organizations can start applying for this year’s Season of Docs. Exciting news indeed! But what happens before April 2? I decided to blog about some ways you can get started with Season of Docs right now.
Open source organizations can start planning the documentation projects they’d like help with, and letting technical writers know about those projects. Get the conversation going, and build up excitement amongst your open source community and amongst the technical writing community.
The first step is to think about a good project or projects that a technical writer can help you with. The Season of Docs website provides some generic ideas for doc projects. You should to craft a specific project or two, based on the actual doc needs of your project. Include links to the relevant docs or other resources within your open source repository or on your website. I’d recommend that you propose a a few different project types, because different tasks may be of interest to different tech writers. For example, you could offer one project to refactor your existing docs, another to create a specific tutorial, and so on.
Your goal is to attract tech writers by making them feel comfortable about approaching your organization and excited about what they can achieve in collaboration with your mentors during Season of Docs.
It’s a good idea to find out who in your community wants to be a mentor. The mentors don’t need to be tech writers. There’s help about the mentors’ role on the Season of Docs website too.
When you’ve gathered some project ideas, blog about the fact that your organization is putting forward an application to participate in Season of Docs. Use the blog post to tell tech writers about your ideas and ask for input. You don’t need to wait for applications to open. You can get a head start by kicking off the discussion now.
Use the tag #SeasonOfDocs when promoting your ideas on social media. To include the tech writing and open source communities, add #WriteTheDocs, #techcomm, #TechnicalWriting, and #OpenSource.