Blog Archives

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.

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.

%d bloggers like this: