Category Archives: open source

More on open source and technical writing

A few weeks ago I wrote a post about how technical writers can help open source contributors get started, and in so doing ramp up our own contributions to open source projects. A colleague has now pointed me to another great post on a related theme: Documentation as a gateway to open source, by James Turnbull.

My post focuses on the complexity of the open source world, which makes it difficult for anyone to get started, even to make a small fix to the source code or the docs. As technical writers, we can help people jump at least the initial hurdles. We can add docs that describe how to complete any relevant licence agreement, edit a code file or a doc page,  send an update for review, and eventually submit the update to the repository. In documenting the process, we become our own test subjects, as we need to go through that very process in order to document it. Sound familiar? It’s what we do best.

James Turnbull’s post takes things further. He describes how to:

  • Find a project that you can contribute to.
  • Consider the etiquette of the open source community that you’ve chosen, before jumping in and making a contribution.
  • Decide what type of edits to make. Both James and I describe READMEs as a good place to start. James goes on to examine strings, errors, and commands, and a few other file types too.

If you’re interested in open source, I recommend James’s post. It’s a good read.

Discovered the Issue Mover for GitHub and it’s super cool

This app makes it easy for me to move GitHub issues from one repository to another within the same GitHub org. I’ve just used it for the first time. It’s a real time saver. And it’s pretty too, especially if you’re fond of ladybirds.

The Issue Mover for GitHub:

What problem does the app solve? Let’s say you belong to an organisation on GitHub with a number of repositories. The number of repos has grown over the months and years, as it inevitably does. As a result, you frequently find yourself needing to move issues from one repo to another. It’s time-consuming to do that by hand. You need to copy across all the content of and comments from each issue, reassign each issue to the relevant contributor, add back all the labels, and finally close the original issue with a note saying that it’s moved.

I’ve jotted down some example use cases. I’m pretty sure you’ll have others in mind too:

Docs: Let’s say, in the earlier days of your project people were adding the doc issues to the code repo. But now you have a website, with its own code and its own repo. So, you want to move the open doc issues from the code repo to the website repo. This is the situation I found myself in. The Issue Mover worked like a charm.

Community: At first, all your community-related requests were lumped together with doc issues. But now you have a large community that’s creating procedures and tools of its own. You create a shiny new community repo and you want to move the relevant issues into it.

Software components: Your app/framework is expanding rapidly, and it makes sense to split off separate code repos for some of the larger, less tightly-coupled components. Of course, the relevant issues should go along for the ride.

General and ongoing: People keep putting issues into the wrong repo! 😉 You like to keep things tidy, and want to move the issues to the logical place.

I was delighted to find this app, and I hope you find it useful too!

Disclaimer: Even though many of the contributors on the Issue Mover project work for Google (and so do I) this is not an official Google Product.

Helping open-source contributors get started

Open-source software (OSS) is a big thing, and becoming ever bigger. Open source gives people the opportunity to contribute to large-scale projects, and it gives those projects the opportunity to gather expertise from the community of experts rather than being limited to employees of any one organisation. The documentation in an open-source project is arguably as important as the software. But it’s often hard for would-be contributors to know where to get started. That’s true for people wanting to contribute to the docs as well as the software. Here’s where we tech writers can help!

One of the biggest hurdles I’ve found as a would-be contributor is that I need to figure out so many peripheral frameworks and tools before I can even think about contributing to the core software or doc that I’m aiming for.

Framework upon framework

I’ve had this experience a couple of times recently. To make one simple change, I need to learn three or four frameworks/languages/tools. In the docs world, these frameworks and tools include Markdown, Django, Read the Docs, Hugo, Netlify, GitHub Pages, and so on. And then there’s git and GitHub… you get the picture.

It’s not even as if you have to learn a framework for each new project. Often the frameworks are stacked on top of each other, and you have to know them all just to make a simple commit to a project. For example, for doc updates a fairly common set includes Markdown, Git, GitHub, Hugo, and Netlify.

Engineers have their own frameworks to learn. On the web side, these may include Angular, Node.js, React, and so on. In the world of containerisation, there’s Docker and Kubernetes. And so on. Wherever you look, you find multiple frameworks piling one on top of the other. These frameworks add flexibility and agility to the software systems, but they also add complexity to the stack of concepts people need to absorb and the tools people need to manipulate.

Tech writer speaking: who’s my audience?

In this world of proliferating frameworks, what can we assume our readers know? The readers in this case are engineers and others who want to contribute to an open-source project. That means they want to make a change in a repository, test that change, and submit it for approval. This is true for the docs too: If a change is anything more than trivial, contributors need to test or preview it before submitting a pull request.

I think we can assume our readers have indepth technical knowledge of one or more languages or tools, but it’s unlikely they have indepth knowledge (or even any knowledge) of all the tools they need to do the job. And so, they come to the docs for help.

Too often, people have to go read the entire Internet just so that they understand how to make a simple change in a project.

As tech writers, this is where we can shine

We can give these tech-savvy people the information they to get started, and point them to more in-depth guides when they need them.

In short, we can show people:

  • The tools our particular project uses.
  • A basic workflow for making a change, including step-by-step instructions for the minimal operation of each tool.
  • Where they can find indepth information about each tool if they need it.

If you’ve recently made a change in an OSS project, or are planning to do so, jot down the steps you needed to take. They’re likely to be what everyone else needs to do too. If the project’s README file didn’t contain enough information to help you, submit a pull request that updates the README based on your experiences.

Even if you don’t have a particular change to make, take a look at the README or contributor’s guide for an OSS project that catches your eye. Does it tell you enough to get started? Would you be able to make a change to the contributor’s guide itself, by reading what’s in it? If not, consider updating the guide and using that experience to compile the steps as you go. It’s a great way to get some OSS contributions in your portfolio.

Examples of contributor guides / READMEs

These are a couple of OSS contributor guides I’ve updated recently:

Other examples:

  • The Kubernetes project has a nice README. I like the way it starts with a welcome!

Doc sprint at Write the Docs day Australia

Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.

Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.

At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:

  • Dart, led by Sarah Maddox
  • Kubernetes, led by Jared Bhatti
  • Cyrus (email), led by Nicola Nye
  • webpack (JavaScript module bundler), led by Chris
  • ReactiveUI.net, led by Geoff

What happened in the sprints

I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:

The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!

At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.

Things people learned

For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.

Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.

For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.

The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.

For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.

It was hard work

It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.

There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.

Swapnil: “Good, OK, I’ll leave you to it.”

Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.” 🙂

Difficulties people encountered

People had trouble with the GitHub workflow at the start of the sprint. For example, when a sprinter first tried to enter a comment on an issue, an email verification request popped up. The experience was confusing.

Some people found it difficult to concentrate in the noisy environment of a sprint, and they felt stressed that they wouldn’t have time to achieve anything in the short time frame of the half-day sprint.

Three hours is a very short time for a doc sprint, particularly when the sprinters are new to the environment and the docs.

Feedback and thanks

If you were at the Write the Docs day, I’d love your comments and feedback on the writing sprints. I’m sure readers of this blog would be interested to know what you learned from the sprints. The owners of the open source repositories would like to know how they can make it easier for people to contribute to the doc sets.

A big thank you to everyone who took part in the writing day and contributed to the docs!

%d bloggers like this: