Blog Archives

Join the Kubeflow doc fixit at Write the Docs AU conference

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.

Registration

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:

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.

Prerequisites

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.

References

How to run an open source doc sprint

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

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:

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.

For the Kubeflow Doc Sprint, I wrote a style guide (that task had been on my radar for a while) and created some very simple templates.

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.

Sprint demos

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.

The aftermath

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.

#protip: Overcommunicate

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.

Earlier posts

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.

Season of Docs is now ready for tech writer exploration

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. 🙂

How open source organizations can prepare for Season of Docs

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.

Season of Docs fostering open source collaboration with tech writers

Exciting news: Google Open Source has announced a new program called Season of Docs. I’m excited because the goals of this program reflect two passions of mine: to help technical writers get started in the world of open source software, and to help open source projects build great documentation. I’m also excited because I’m on the program development team for Season of Docs.

Season of Docs sets up a framework for open source projects to invite technical writers to work on the projects’ documentation for a few months.

Technical writers bring their documentation expertise to the open source project of their choice. In return, mentors from the open source organization help the technical writer gain an understanding of their open source community, processes, tools, and code.

A golden collaboration

When technical writers contribute to open source projects, both parties benefit. The open source project gains good documentation and improved contribution procedures. The technical writer gains experience in open source software, developer-focused products, new tools, and the ways in which open source communities work. A golden collaboration.

Open source is great. Some of the world’s most-used software is open source: the Linux operating system, Firefox web browser, LibreOffice, Apache web server, to name but a few well-known brands. Large companies like Microsoft, Google, Red Hat, and IBM contribute to, as well as use, open source code.

Open source ideology is great too. People share code in public repositories, collaborate on making the code better, invite others to join their communities… yet, all too often, people expect those newcomers to understand the product, the code, and the community’s values with very little good documentation.

Why the dearth of good docs? It’s clear from GitHub’s Open Source Survey that open source organizations know the value of good documentation, so why are there so many gaps? Because writing documentation is hard.

But wait… there are people who know how to do it well!

Many technical writers are keen to gain experience in developer-focused products such as APIs, SDKs, and various programming languages and tools. Technical writers look for opportunities to explore cloud computing, machine learning, hardware, and more.

When a technical writer wants to expand their resume or look for a new role, the advice is sometimes to build a portfolio by contributing to open source. But that’s not easy. There are so many open source projects out there. Where do you start? How can you be sure your contributions will be useful to the open source project? Who can help you understand the contribution procedures, the product, and the code?

Season of Docs gives technical writers and open source projects the opportunity to work together within a structured program.

Let’s go build great open source docs!

How does Season of Docs work?

First up, open source organizations apply to participate in Season of Docs. The list of accepted organizations is then published on the Season of Docs website, along with the ideas each organization has proposed for technical writing projects.

Then technical writers explore the list of participating open source organizations and their project ideas.

As a technical writer, you can decide which open source project you’d like to work with. It’s a good idea to get in touch with the open source organization to chat about their requirements and your own ideas. You can contact more than one organization if you like.

When you’re ready, you submit your application to participate in Season of Docs, including your project proposal and the name of the open source organization you’re interested in. You can submit more than one project proposal, but only one will be accepted.

If your technical writing project is accepted for Season of Docs, then you as a technical writer will work with your chosen open source organization for a few months (starting in September 2019) to complete your project. You work closely with your open source mentor for the duration of the program, to ensure successful completion of your project.

At the close of the program, the successfully-completed projects are published on the Season of Docs website and on the Google Open Source Blog.

When can you start?

Open source organizations can start applying to participate in Season of Docs from April 2, 2019, and the website will show the list of participating organizations on April 30. Technical writers then have the opportunity to examine the list of participating open source organizations and explore the project ideas proposed by the organizations.

Technical writers can start applying to participate in Season of Docs from May 29, 2019.

The Season of Docs timeline shows the key dates and what happens in each phase of the program.

Want to learn more?

Take a look at the Season of Docs announcement on the Google Open Source Blog, or dive into the guides on the Season of Docs website at g.co/seasonofdocs. Join the mailing list at season-of-docs-announce to stay informed about when applications open and other important program events.

%d bloggers like this: