The art of documentation for open source projects – 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.

Ben Hall‘s talk was about how important documentation is to open source projects, and the changes communities can make to improve their documentation.

This statement from Ben’s introduction rings true with me:

While many open source projects have amazing code bases, the documentation is letting them down and as a result they are losing influence and opportunities for adoption and feedback.

I’ve worked on the docs for a few open source projects, and it’s hard. 🙂

Here’s what Ben talked about:

  • Where docs fit into the user journey
  • How docs support users
  • Examples and inspiration for docs

These are the types of people who use the docs: potential users (people who’ve heard about the project and are interested in starting to use it), implementers, maintainers, and contributors.

There are a few myths about docs, including that no-one reads, and definitely no-one wants to write docs, yet the docs must exist. Ben says to address this type of thinking, we need to analyse the types of documentation people need, what they want to read. For example, avoid large blocks of text. No-one wants to read them, and writing them is hard.

Docs for new users

Consider how people approach the docs:

  • The commitment pattern is very rare – this is where the reader sits down and reads the entire text from top to bottom.
  • The layer-cake pattern is more common – people scan for headings and for things that are interesting to them.
  • The spotted pattern is where people look for specific items e.g. a specific guide. This is also common, especially when people have used the product before.

Someone starting with the project may ask themselves: Does this project solve my problem, and will it help me with my career? Note that the README will probably be the first doc a person reads. So pay attention to it, and make sure it gives people a good overview and signposts to where to go next.

Avoid saying something is simple, or tell them to just deploy using x. Rather, showcase the project in the smallest amount of time, to help them decide whether the project is right for them. Examples are the best way of doing this. (Short videos and GIFs are often used too, but people have to download and watch them, which may be discouraging.)

Kubernetes, for example, has an interactive element in the website which gives people a feel for the project. Stripe found a significant advantage when they included interactive snippets in their website. Realistic blocks of code where you can see the core aspects of the product working.

A good tip is to include snippets of code in the docs, and link directly to GitHub for people who want to see the rest of the code.

We also need to make docs inclusive. Take care with the examples we use. Respect the fact that not everyone’s first language is English. Don’t use words like “it’s simple” or “just do this”, because for many people it’s not simple. Avoid making the user feel bad. The problem is ours, we need to make the software as simple as possible, and the docs should acknowledge that.

Docs for an active user

Active users of the project have needs that differ from those of new starters. They want to solve other problems, or find a solution for something that’s broken.

We need to focus on how people can find what they’re looking for. Discoverability in the docs. Ben gave the example of the Twilio docs, which ask readers a few questions before deciding where to take them.

If something is broken, consider the user’s emotional state at this time. They probably don’t want to read a lot of text at this time. StackOverflow and GitHub Issues have become key resources for this type of use case. When writing our docs, we need to acknowledge these resources. For example, point people to an issue and make sure the issue is informative.

Docs for community contributors

We must make sure there are good contributor guidelines. Make sure people feel safe, by including a code of conduct. Include a licence so people know the terms under which they’re contributing.

See the Kubernetes and Microsoft Azure docs for examples of great contribution guides.

Consider running a doc sprint where contributors can come and talk to project maintainers about becoming a maintainer themselves. Also working groups and contributor summits have huge impacts on showing people how they can improve their contributions to projects.

Three key points from Ben

Developers experiment. The docs should support this mindset.

Users get into trouble. Make sure we provide doc types that support the fact that people encounter problems.

We should encourage contributions. Not only the code base should be open source, but also the documentation.

In closing

From Ben: Having amazing documentation becomes your key differentiator.

From me: Thanks for a great talk, Ben, and +1 to fostering amazing docs for amazing open source projects.

Fostering diversity in open source projects – panel discussion 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 and to the audience who contributed ideas during the session.

Orna Berryman moderated a panel discussion titled “Growing Diversity in Open Source Projects”.  The speakers were Jasmine Jaksic, Lin Sun, and Limin Wang. The goal was to focus on how we can increase the number of people with different backgrounds, skill sets and experience working on open source projects.

The statistics for  the number of women in open source communities are around 3-5%. Orna put a question to the panel about why this may be the case. This compares to 20-30% in tech companies. One reason may be that there’s no regulation of bad behaviour in open source, such as instituting a code of conduct. More than 40 000 projects have already adopted one, many of them based on Contributor Covenant.

Another way to tackle the lack of diversity is to say something. Often, if someone addresses a problem immediately, the perpetrator will stop offending.

Imposter syndrome afflicts people starting on an open source project. There are a few ways to tackle imposter syndrome. Label issues with “help wanted”, or some way of indicating that an issue is a good place for a starter to contribute. Also provide mentoring for new starters, and recognise their work.

Communicating remotely can be intimidating. It’s hard to share your thoughts, and sometimes your thoughts are so different from the rest of the community that the community doesn’t appreciate them. (No-one +1s your comment.)

Travel is hard for some contributors, especially those who have young children. This makes it difficult to travel to conferences.

A question from the floor: what about governance? We can’t rely on an honour system. A code of conduct can’t do everything. We need to have governance over the community. The open source projects need to ensure there are members who monitor the behaviour within the community, and to take responsibility for that behaviour. Large organizations, such as the Linux community, should encourage this type of monitoring. The responsibility also belongs to every person in the community. Step in if you see bad behaviour happening.

People hesitate to join communities where they don’t see people who they can identify with. So communities should keep diversity front and centre.

Contributing to the community should be seen as of equal importance as contributing to the code. No matter how valuable someone’s code contribution, or how large their following, we should follow up on any bad behaviour by that individual.

Question from the audience: Is there a community where we can send people who need to create contacts? There are mentorship programs, such as Google Summer of Code for students. has a number of projects where you can sign up. There’s also for students who want to enter the open source community. and which focuses on diversity. If such programs can pay people, or provide childcare, this will make things easier for people with young children.

From the point of view of hiring new employees, open source contributions are viewed as more important than an internship. Employers should encourage people to work on open source projects, which are equally valuable to their CVs.

From me: Thanks to the panel for an interesting discussion. The points above should be useful especially for new open source projects, as well as for open source contributors.

Report from Write the Docs Australia conference

Last week I attended Write the Docs Australia 2018 in Melbourne. Around 100 documentarians gathered to discuss words, code, style, and other essentials relating to technical documentation. There was plenty of food and fun too.

“What’s a documentarian,” you may be wondering? In Write the Docs parlance, a documentarian is someone who cares about documentation. Documentarians include technical writers and communicators, as you’d expect, but also UX writers, software engineers, marketing content writers, and more. If you think docs are a Good Thing, you’re in. 🙂

Approximately 100 people attended Write the Docs AU this year. Attendees came from Australia, the APAC region, and around the world. The following photo is from the Write the Docs photo set on Flickr:

Talks, workshops, and unconference sessions

The talks included:

  • Lana Brindley: Facebook, Dynamite, Uber, Bombs, and You
  • Mike Hamilton: Responsive Content – Presenting Your information On Any Device
  • Kristine Sihto: The Art of Consistency – Creating an inhouse style guide
  • Abhay Chokshi: UX writing – Let your product speak
  • Alexandra Perkins: Making Yourself Redundant on Day One – Internal documentation to teach the next hire what you’ve learned
  • Matthew Borden: Good Code, Bad Code & Code Review
  • Nicola Nye: The subtle art of interrogation
  • Daniel Stevens: Creating experiences with information!
  • Laura Bailey: Backseat Content Strategy
  • Mathew Patterson: Power up your support team to create better documentation

In addition to the presentations, we heard a number of informative, entertaining lightning talks. People could choose to attend one or more workshops and run or participate in a few thought-provoking unconference sessions.

These were the workshops:

  • Sarah Maddox: Tech Writing 101
  • Sara Marek: Let’s create a Style Guide!
  • Jessica Parsons: Static Site Generators, What, Why and How

Tech Writing 101 workshop

Around 50 people attended the Tech Writing 101 workshop, which I ran with the able help of Eric Gilmore.

This tech writing stuff is hard. But fun!

Tech Writing 101 is a two-hour workshop on the principles and techniques of technical writing. It leads the participants through a series of pair-work exercises to improve the clarity, readability, and effectiveness of their writing. You can read more about the workshop on the Write the Docs AU page.

By the end of the session, participants also think differently about toothbrushes.

The workshop pre-reading is available in LisaFC’s GitHub repo. A number of the workshop attendees let me know that they plan to introduce that pre-reading to their colleagues, as it’s a great introduction to the patterns of clear writing.

Photos and videos

Photos are in the Write the Docs photo set on Flickr. Videos of the presentations are in the Write the Docs AU playlist on YouTube.

Tweets and write-ups

Read the tweets at #WriteTheDocsAU. Here’s one of them from Nicola Nye:

Have you written a report on the conference, or come across someone else’s writeup? Let me know by adding a comment to this page or tweeting @sarahmaddox!

My takeaway from the conference

So many people who’re passionate about docs! It was a privilege chatting to engineers, UX designers and writers, and marketing folks, as well as other technical communicators. Thanks to everyone for a great conference!


Shutting down Tech Comm on a Map

Hallo folks, I’ve decided to take down Tech Comm on a Map—this means I’ll remove the web page and unpublish the Android app. The web page will remain available until the end of November, to give people time to fix up any pages that are using it. The Android app will remain installed on your device if you’ve previously installed it, but it won’t be available for new installations.

Why am I taking them down? I don’t have bandwidth to look after them any more. The web app is suffering from a technical problem that I can’t fix, despite quite a bit of effort. On the Android side, I don’t currently use Android technology, and it therefore takes quite a bit of effort to get back into the swing of things each time I need to make a change to the app.

The usage stats for the apps are reasonable, but not huge. The web page gets a max of 50 visitors per day, measured over the last 6 months. There are 27 active installations of the Android app.

I’ll leave the code available in GitHub (web app, Android app) at least for a while, for those people who want to try it out.

Thank you to everyone who has contributed data and code to this project! It’s been a rewarding experience developing the apps and working with contributors to the code and the data.

If my taking down the apps will cause you any trouble, please do let me know.



What is a quickstart to you?

When someone asks you to create a quickstart guide, what do you envisage? More importantly, what does the requester envisage, and what do your readers expect from such a doc? Is a quickstart the same thing as a getting-started guide? Are you all starting on the same page? 😉

I’ve found that people mean different things when they talk about quickstart guides. Confusingly, people mean different things when they talk about getting-started guides too. For some people, quickstarts and getting-started guides are the same thing, but people differ about what that thing actually is. For other people, quickstarts and getting-started guides are separate docs with disparate goals.

As a result, when people get together to discuss the requirements for such a doc, the discussion can be long and complex. Debate may become quite heated. At that point, it’s a good idea to take a step back and check everyone’s initial assumptions.

I started this post with a number of questions. It may have felt like a barrage of questions! Actually, the crucial question is this:

“Who is the intended audience for the guide?”

Here’s an approach that appeals to me:

  • A quickstart guide is for domain experts.
  • A getting-started guide is for domain newbies.

Let’s take a look at how the approach pans out.

Quickstart is for experts

The quickstart is for readers who know the problem space and know exactly what they need to do.

As a user, I know what I need to do. Just show me how do it with your particular product.

These are domain experts. They know their field. Your product targets one or more tasks in that field. The experts have performed the tasks untold number of times, using various tools and processes. Now they just need to know how to drive your specific product to complete the task.

In the quickstart, they need to see:

  • Where to find the product. This may be a web address, or a download link, or an address to a brick-and-mortar store.
  • How to get any required access keys or authentication credentials.
  • How to configure the product. For a developer-focused product, this usually involves creating a hello world application. For an end-user product, this may mean setting up a corporate or user profile and choosing other preferences.
  • How to get started. This is often a walkthrough of a simple but common use case, which helps the reader learn the patterns of your product and map your terminology to theirs.

The domain experts don’t need the following information in a quick start guide (though they should have easy access to these items if they do need them):

  • Detailed descriptions of the concepts relevant to the domain and the product.
  • A detailed walkthrough of a complex use case.
  • Explanations of why they’re performing each step.

Here’s an example of a quickstart guide for Google Compute Engine.

Getting-started guide is for newbies

The getting-started guide is for people new to both the problem space and the product.

As a user, I’m not sure exactly what I’m doing here. Help!

They need an introduction to the most important concepts, full context about each step they’re performing, and detailed setup instructions.

Typically the guide needs to assume some existing knowledge of the problem space. The writer needs to decide just how much prior knowledge to assume.

The guide to creating and starting a virtual machine on Compute Engine is a good example. It’s not titled as a getting-started guide, but I think it has the characteristics of one. It assumes the reader knows what a virtual machine is, but gives them plenty of context from that point onwards.

The marketing approach

I’ve had a number of interesting discussions with marketing teams about what should be in a quickstart or a getting-started guide. These discussions don’t generally distinguish between the two types of guide. The marketing approach views the document as an introduction to the values your product offers, why people should use it, and who else is using it.

The target audience is usually the business decision maker – the person who’ll decide whether to buy the product.

The product overview for Compute Engine is an example of such a doc.

What to do about these varying interpretations?

If people are coming to our docs with different expectations of what they’ll find in a quickstart or a getting-started guide, how can we ever hope to satisfy them all?

An ideal solution is to describe the purpose and intended audience at the top of the doc. Make it clear what people can expect before they commit to reading the doc.

That simple step may help prevent numerous complaints and negative ratings on our docs. Even better, it’ll help numerous readers know what to expect or at least send them away with a smile rather than a frown.

If people are coming to meetings with different expectations of the doc we’re building, how can we ever hope to get agreement?

A good solution is to make sure we’re all using the same terms and definitions at the start of the meeting. For example, the Compute Engine docs have clearly defined “product overview” and “quickstart” guides, and a getting-started guide in the “how-to guides” section. If people can agree on a breakdown of document types that suits the organisation, then everyone knows where to channel their energies. We’re all on the same page!

Best explanation ever

Here’s the best explanation I’ve seen of the purpose of a guide, from the Jupyter/IPython Notebook Quick Start Guide:

“Briefly, if someone gave you a notebook to run and you don’t know what a notebook is, this document is for you.”

And yes, Jupyter’s definition of a quick start guide differs from mine. Plus, they use two words for “quick start” instead of one. 😀

%d bloggers like this: