Category Archives: open source

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.

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.

KubeCon Seattle 2018 – open source, docs, community

This week I attended the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. It was huge, friendly, interesting, inspiring.

Most of the conferences I attend are tech writing conferences. This is the first time I’ve attended a highly “technical” software conference, and I wasn’t sure what to expect. Would all the sessions fly right over my head? Would the other attendees view me as an interloper? Would documentation feature at all? The answers are, “well yes some”, “no”, and “yes”!

KubeCon was huge. This year there were 8 000 attendees, which is eight times more than the last time the conference took place in Seattle, in 2016. It’s twice as many as last year, when the conference was in Austin, Texas

Part of the room in which the keynotes were held:

KubeCon revolves around Kubernetes, an open source system that helps people deploy and manage containerised applications. The Kubernetes website saw 1.8 million visitors last month. A keynote speaker, Liz Rice, remarked that these numbers make the Kubernetes website massively more popular than the Seattle Seahawks but less visited than Starbucks. What’s more, the Kubernetes readership has just started exceeding that of the Manchester United website!

A Kubeflow end-to-end workshop

I took part as teacher’s assistant (TA) for the Kubeflow end-to-end workshop, run by Michelle Casbon and Amy Unruh. Kubeflow is a framework that helps make it easier to deploy and manage machine learning systems. (I work on the Kubeflow docs.) The Kubeflow session at KubeCon took the form of a codelab which was rewarding in that it showcased some very cool technology in a graphical way, though, as is still the case with most machine learning systems, the workflow was somewhat complex. (This is something we’re working on.) I’m very pleased I was able to help many people get their apps up and running.

Awaiting the start of the Kubeflow workshop:

Notes on sessions related to open source docs and community

I blogged about some of the other sessions I attended – those related to docs and/or community:

Thanks

Thanks to the conference organisers, presenters, and attendees. I had fun, met good people, and learned a lot.

It was invigorating to attend an event where the technology and the community are thriving, growing, excited, and yes, just slightly chaotic. This year Kubernetes won the OSCON Most Impact award (OSCON = Open Source Convention). The word “community” is on everyone’s tongue, as much as the word “code”.

This is Seattle. It rained, but rain did not dampen our spirits.

Crossing from one conference building to the other in the Seattle rain:

Update on 19 December: KubeCon videos are available

The talks and other sessions are available on the Seattle ’18: KubeCon and CloudNativeCon playlist on YouTube.

How to bootstrap an open source project – talk at KubeCon

This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.

Peter MacKinnon talked about bootstrapping Kubeflow, an open source project that aims to provide stability, composability, and portability for machine learning workflows. His talk was entitled “Eco-Friendly ML: How the Kubeflow Ecosystem Bootstrapped Itself“. Peter discussed how an open source project can rapidly achieve its potential by working with other projects, and how those inter-project collaborations enrich the entire Kubernetes community.

About Kubeflow

Peter gave a quick overview of Kubeflow, and how it helps people develop a machine learning (ML) pipeline. The goal of the Kubeflow project is to enable machine learning for everyone. This is a difficult problem to solve.

The Kubeflow team started with a mission statement: The ML pipeline should be portable (from bare metal to cloud), scalable, and composable (a micro-service architecture).

Then the team decided on a baseline platform – Kubernetes fits the bill. From this decision came the goal:

Anywhere you can run Kubernetes, you can run Kubeflow.

Open is key

To bootstrap an open source project, get in touch with other communities and see what they’re working on and whether their goals align with yours. Look at blogs, forums, conferences. Talk to people, in person, at conferences, on Slack. Get involved. Go deeper on GitHub – raise issues, contribute to your chosen projects by raising pull requests.

Observe the open source etiquette. Get your git technique right, help other people with those techniques, and respect the community of the projects you’ve chosen.

The Kubeflow tech

Peter talked us through some of the technical projects that Kubeflow has integrated with. The examples he gave were ksonnet, Ambassador, Argo, JupyterHub, Kaggle, RAPIDS AI at NVIDIA, TensorFlow, Pachyderm, Arrikto, and SeldonIO. You can see some of the details in the Kubeflow docs and on GitHub.

The Kubeflow team holds open conversations with these related projects, so that they can work together to develop solutions that are advantageous to all.

What makes a good community?

Kubeflow has a strong code of conduct, based on the Cloud Native Computing Foundation (CNCF) code, with the goal of ensuring a harassment-free experience for everyone. They have documented community standards and conflict resolution protocols, and they work with other communities in their ecosystem to support the same standards.

The power of open source

Peter says Kubeflow is a great community. It’s only a year old, and he has a lot of fun there. Everyone wins when communities collaborate, and Peter encourage contributions and ideas from other communities. Open source communities, when they work well, give contributors a sense of empowerment and achievement beyond what they do in their day job.

Thanks

Thanks Peter for an engaging look at a new open source community.

Open source, community, development – talk at KubeCon

This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.

Craig McLuckie, one of the Kubernetes founders, talked about how the Kubernetes project approached the community at the start of the project, and how that approach has shaped the future and success of the project.

From Craig:

“If it can be open sourced, it should…”

If you want to build a widely-accepted infrastructure technology, it has to be open sourced.

Open community from the start

Open source is important, but just as important is open community. Craig talked about how well Docker succeeded with this philosophy of focusing on the community, and how the Kubernetes team decided to follow the same philosophy. At the beginning, the team didn’t know exactly how to do this, though they had some ideas. They spent a lot of time thinking about how to build a magic community. The Kubernetes team were fortunate in that the team “clicked” – they worked very well together.

RedHat, Google, CoreOS all brought a lot of DNA in an open manner. The original group didn’t try to hold on to power. They realised that this wouldn’t scale, and they created the structures that would enable them to step back. Craig sees this as remarkable – he hasn’t seen it anywhere else.

Code and design in the open

Ship early and iterate quickly. This is like presenting an open design philosophy in code. Don’t worry about losing secrets to competitors. Iterate quickly and share the design and results with your customers. Share the roadmap in the open too. Your competitors will work with you.

What is the role of the foundation, CNCF?

It’s vendor neutral, provides structure, creates resources. But there’s another critical function: the foundation is a referee. It creates an environment where the end users can watch the creators and report any problems. The End User Community represents the people who have to live with the decisions of the rest of the foundation.

Balancing the pros and cons of open source

Open sourcing a project brings you adoption and engagement, but has disadvantages too. You lose some control and velocity, and gain some operating overhead. It’s always a matter of weighing adoption on the one side against the vectors on the other side, particularly if you want to commercialise the product.

If you develop something in a closed environment and surprise people when you launch it, be aware that people may surprise you in turn. If you develop in the open, you get useful feedback.

Marketing a launch

Don’t you lose a promotion and advertising opportunity if you develop at a slow burn? Not necessarily. There’s an advantage to a long buildup of news too.

Practical tips on how to design in the open

This was a question from the audience.

A friend of Craig’s, Evan from Knative, contributed to these points. The Knative team started thinking about Knative about six months before making the announcement. They wanted something to show rather than coming in with an open slate and asking the highly-opinionated community for comments. The team thought about who they wanted to bring on board as partners. They came up with RedHat who had similar offerings in OpenShift and Cloud Foundry. For the first 5-6 months, most of the development was done by Google, although there were other contributors too.

Consider another example, Istio, who threw the gates open very early, and that slowed things down at the beginning.

For small projects, on the other hand, it’s unlikely you’ll be deluged with ideas and contributors. So in that case, it’s a good idea to talk about it in the open and engage interest.

Having a roadmap and knowing what you want to do is very important.

When in doubt, remember that it’s better to ask for forgiveness than for permission.

Conduct experiments. Try things in low volume first. Stop when something isn’t working.

Thanks

Thanks to Craig for an interesting look at the philosophy of open source community.

%d bloggers like this: