Writing internal vs external docs: what’s the difference

During most of my career as a technical writer, I’ve written and managed documentation for external users — that is, users who’re not part of the same organisation as I am. Sometimes this type of documentation is called customer-facing docs. I’ve also worked on open-source docs for a couple of years. And now I’m working on internal documentation — that is, docs for people working within the same organization (in this case, Google). For most of my tech writing career, the audience has been developers (software engineers), whether they be external or internal. What’s it like working on internal vs external docs?

I started on internal docs almost three years ago. As soon as I started this role (actually, even before that, when I was preparing for the interview for the role), I started thinking about the differences and similarities between writing for internal and external audiences.

My assessment: Writing and managing the docs for an internal audience has more similarities to working on open-source docs than to working on docs for an external audience.

Here are some thoughts about where working on internal docs differs from working on external docs. In internal docs:

• Your audience has access to the code of the system that you’re documenting. Often, the users can put questions to the developers, either directly through some type of chat system or through an issue tracker. A point of interest is that, for better or worse, the users can often get in touch with you, the technical writer, in the same way!
• The engineers who’re developing the system are likely to value the docs and to contribute to the docs when they add a new feature or make a significant update to the system.
• The (internal) engineers who’re using the system can (and do) update the docs too.
• Some techniques that work in open source also work in internal documentation. I’ve added some suggestions in this post.

What remains the same:

• There are never enough technical writers to go round. However, I think this problem is easier to work around when you’re on the internal docs, if your organisation gives you enough leeway.
• The work of a technical writer is immensely valuable. Even when other people contribute to the docs, the technical writer is the one who makes it all make sense.

Organize doc sprints or doc fixits to encourage and enable contributions

In the world of open source, doc sprints are an oft-used pattern for encouraging users to contribute to the documentation. A doc sprint is an event (usually 2 to 3 days) when people get together to write documentation about a specific product or tool. A doc fixit is similar, but the goal is to fix a set of miscellaneous documentation issues (bugs) rather than to create a new set of docs.

Doc sprints and fixits are very useful:

• You and the engineers can time-box the documentation updates. When you give people a specific period within which they’ll be doing this one thing, it leads to efficiency in time usage and gives people a sense of certainty about their goals.
• A number of people will be working on the same doc set at the same time. This makes it easier when you want to ask questions and get advice, as you’re not pulling people away from other work.
• Taking part in a doc sprint or fixit gives an engineer confidence in their ability to update the docs. They can learn from you and others during the event, and take away a set of tips and tools for their next foray into the doc world.
• You can create a buzz around the event, which helps to motivate people to take part.
• You might even be able to scrape up some budget for snacks, muffins, or the ever-important chocolate!

If you’re interested in running a doc sprint or doc fixit, you’ll find some useful tips in an earlier post: How to run an open source doc sprint. Depending on the size of your organization and the number of engineers who might take part, many of the techniques in that post are useful for an internal doc sprint or fixit. I’ve written a few posts about doc sprints and doc fixits over the years. 

Use the same tools as the engineers

If possible, set up your documentation-publishing stack to use the same tools as the engineers when it comes to change reviews, issue tracking, and source location. This philosophy is sometimes called docs as code.

For me, the biggest advantage is that engineers who want to contribute to the docs don’t have to learn an entirely new tool set. This is particularly important given the fact that most engineers will only contribute periodically to the docs, and will therefore need to re-learn the tool set each time.

Train the engineers in the basic techniques of technical writing

In the environment where I work, an important part of the role of technical writer involves coaching engineers in how to structure and write docs. Why? Because there’s one thing that’s common to all TW roles I’ve ever worked in: there are never enough tech writers to go round. So we have to figure out how to make the best use of our time, how to have the most impact in furthering the goals of our teams and our organization.

For engineers, clear writing is an important skill to add to their skill set. Apart from user-facing docs, engineers need to write design docs, reports, and other communications. Being able to communicate well is a distinct advantage in their career. The technical writing courses that we offer are always over-subscribed by a factor of two or more.

If you’re interested in running a short course that teaches engineers the basic concepts of technical writing, take a look at the tech writing courses published by Google.

A related tip is to share more than knowledge: Provide templates and examples of information architecture that engineers can use to build their own doc sets.

Emphasize the concept of audience

A particularly important concept to help engineers understand is that of audience. Who are they writing for, and what does the reader need to know.

This is particularly hard when an internal engineer is writing for an audience of other internal engineers. The engineers creating the system are likely to think that they know their audience well. After all, the audience is the same as the authors, right?

Yes and no. Yes, they have much in common. No, their information needs are not the same.

Internal systems are like a stack of bricks. Engineers creating one layer are building on the lower layers. In a well-designed stack, the higher levels use APIs or other frameworks provided by the lower layers.

Therefore, an internal engineer doesn’t necessarily want to know the ins and outs of the systems they’re building on top of. Such knowledge can be useful, sure, and is most likely interesting. But the engineer’s key need is to understand how to use the APIs and frameworks. To take that oft-used metaphor of driving a car vs being a mechanic: It certainly helps you drive better if you know how the car is put together. It also increases your enjoyment of driving. But do you have the time or inclination to learn in detail how everything works before you drive the car? No.

Here’s a related post of mine from way back in 2014: The documentation that developers need to do their jobs.

What does ChatGPT have to say on the topic?

I asked ChatGPT, for its response to this question: As a technical writer, what’s the difference between an internal engineering audience and an external engineering audience?

ChatGPT:

As a technical writer, the distinction between an internal engineering audience and an external engineering audience refers to the intended audience for the technical information being written.

An internal engineering audience typically consists of engineers, researchers, and technical staff within the same organization. This audience is likely familiar with the company’s internal terminology, processes, and systems, and may have a deeper understanding of the technical information being presented. When writing for an internal engineering audience, technical writers can use more technical jargon and assume a higher level of prior knowledge.

On the other hand, an external engineering audience may consist of customers, partners, suppliers, or other stakeholders outside the organization. This audience is likely less familiar with the company’s internal terminology, processes, and systems. When writing for an external engineering audience, technical writers need to be mindful of using clear and concise language and avoiding technical jargon that may not be familiar to the reader. Additionally, technical writers may need to provide more background information and context to help the external audience understand the technical information being presented.

In summary, the difference between an internal engineering audience and an external engineering audience lies in their level of familiarity with the technical information and the company’s internal processes and systems. Technical writers need to adjust their writing style and level of detail accordingly to effectively communicate technical information to these two distinct audiences.

That’s pretty spot on!

What have I left out?

Let me know. 🙂

How to add a banner to website pages using Hugo

A while back, I needed to display a banner on every page of a documentation website. Furthermore, I wanted the banner to appear only under specific conditions. We use Hugo as the static site generator for the website. Here’s what I figured out, using Hugo templates.

I wanted to add a banner to the archived versions of the Kubeflow documentation, such as v0.7 and v0.6, letting readers know that they’re viewing an unmaintained version and pointing them to the latest docs.

Here’s an example of such a banner:

In Kubeflow’s case, the purpose of the banner is to catch people who enter the archived documentation from a web search and make sure they realise that a more up-to-date set of docs is available.

Summary: Adding a banner to a page with Hugo templating

In essence, you need to do the following:

• Figure out which Hugo layout file is responsible for the base layout of your pages. In the case of the Kubeflow docs, the responsible layout file is at layouts/docs/baseof.html. You can see an example of the layout file in the Docsy theme: layouts/docs/baseof.html. (Kubeflow uses Docsy on top of Hugo.)
• Add the code for your banner to the layout file. Or, even better, create a partial layout, often called just a partial. A partial is a snippet of code written in Hugo’s templating language. Put the code for your banner into the partial, then call the partial from the base layout. For the Kubeflow version banner, the code sits in a Hugo partial named version-banner.html.

There’s an explanation of the code later in this post.

Making the banner’s appearance conditional

In order to offer docs for multiple versions of Kubeflow, we have a number of websites, one for each major version of the product. The overall configuration of the websites for the different versions is the same. For example, we have the current Kubeflow documentation, and archived versions 0.7 and 0.6.

I wanted to make sure we had to do only minimal extra configuration to cause the banner to appear on the archived doc sets. I didn’t want to have to edit the layouts each time we create an archive. A good solution seemed to be a parameter that we can set in the site’s configuration file.

How it works – first the configuration settings

The parameter that controls the appearance/non-appearance of the banner is named archived_version. If the parameter is set to true, the banner appears on the website. The parameter value is false for the main doc site, kubeflow.org. When we create an archived version of the docs, we set the parameter to true.

The parameter is defined in the site configuration file, config.toml. The configuration file also contains a version number and the URL for the latest version of the docs. Both these fields are used in the banner text.

Here’s a snippet showing the relevant part of the configuration file:

# The major.minor version tag for the version of the docs represented in this
# branch of the repository. Used in the "version-banner" partial to display a
# version number for this doc set.
version = "v1.0"

# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
archived_version = false

# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = "https://kubeflow.org/docs/"

How it works – the content and logic

For the Kubeflow website, a Hugo layout file is responsible for the base layout of the documentation pages:layouts/docs/baseof.html. You can see an example of the layout file in the Docsy theme: layouts/docs/baseof.html. (Kubeflow uses Docsy on top of Hugo.)

I inserted the following line into the base layout:

{{ partial "version-banner.html" . }}

The above line calls a Hugo partial named version-banner.html. The partial contains the banner content and logic. (I’ve contributed the logic for the version banner to Docsy, which is why the URL leads to the Docsy repository.)

Below is a screenshot of the content of the partial. Unfortunately I can’t paste the code, because WordPress strips out all HTML:

You can copy the code from the partial: version-banner.html.

The code does the following:

• Check the value of the archived_version parameter. If true, continue to the next step.
• Get the value of the url_latest_version parameter, for use in the banner content when giving readers a link to the latest version of the docs.
• Get the value of the version parameter, for use in the banner content when showing readers the version of the website that they’re viewing.
• Create an HTML div containing the styling and content for the banner.

Here’s the screenshot of the banner again, so that you can compare it to the HTML div:

Docs or it didn’t happen

I created a user guide for other people who want to use the banner logic on their sites using the Docsy theme: How to display a banner on archived doc sites.

I also updated the release procedures for the Kubeflow engineering/docs team, explaining that we must set the archived_version parameter to true when archiving a website version.

In closing

I hope this post is useful to you, if you find that you need to add a banner to a website using Hugo templating!

How to update your PR on GitHub

So, you’ve created a pull request (PR) on GitHub, and you’ve received some review comments. Now you need to update the PR to address the comments. How do you do that? This post shows you how to update the files in an existing PR, using either the command line or the GitHub UI.

When you ask how to update the files in an existing PR on GitHub, the answer is usually something like this:

Just push the updates to the same branch and GitHub takes care of it automagically.

Well, it’s true. GitHub does take care of it, and it is fairly magical. But how do you “just push the updates to the same branch”?

It took me a while to figure that out, the first time I needed to update the files in a PR. You can do it using command-line Git or using the GitHub UI. I prefer the command line, as it’s usually cleaner and simpler in the end, particularly if you need to update more than one file.

First, of course, you need to create the initial PR. If you haven’t yet created a PR, you can follow this guide to working on GitHub, which I created for the Kubeflow open source doc set that I’m currently working on.

I’ll assume that you already have a PR and that you need to update one or more files in that PR. Below are instructions on how to use the command line or use the GitHub UI.

Using the command line to update the files in a PR

Prerequisites:

• You need Git on your local computer. See the Git installation guide.
• If you don’t already have a Git repository on your local computer with a branch for your PR, create the local Git repository and branch now. See my blog post on how to download a PR from GitHub to your local computer. This process is necessary if you’ve been working online using the GitHub UI up to now, or if you’ve used a different computer to work on this PR up to now.

Follow these steps to update the PR:

1. Open a command window on your local computer.
2. Go to the directory containing the GitHub repository on your local computer. The command below assumes that you’ve cloned the repository into a directory named git-repositories/awesome-repo:

   cd git-repositories/awesome-repo

3. Tell Git to check out the relevant branch. In this example, replace your-branch-name with the name of your branch:

   git checkout your-branch-name
   

4. Run git status to check the status of your local files. Make sure the response shows that you’re in the branch that you expect to be in, and that there are no uncommitted changes in your local repository. (It’s a good idea to run git status regularly, just to check that things are as you expect.) If there are uncommitted changes in your local repository, you should take a look at them and consider committing them and pushing them up to GitHub before going any further. The result from git status should look like this:

   On branch your-branch-name
   nothing to commit, working tree clean
   

5. Run the following command to pull down the most recent changes from your branch on GitHub to your local repository. It’s fine to run this command even if there are no changes to pull:

   git pull origin your-branch-name
   

6. Update the files that you need to change. You can add, edit, and delete files using your favourite text editor. I’m currently using Visual Studio Code.
7. Run git status to check the status of your local files. The response should tell you which files you still need to commit for Git tracking. For example, the following status response shows one changed file, named your-updated-doc.md, that you still need to commit:

   On branch your-branch-name
   Changes not staged for commit:
     (use "git add ..." to update what will be committed)
     (use "git restore ..." to discard changes in working directory)
   	modified:   your-updated-doc.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

   Another example: The following status response shows one deleted file and one added file, both of which you need to commit for Git tracking:

   On branch your-branch-name
   Changes not staged for commit:
     (use "git add/rm ..." to update what will be committed)
     (use "git restore ..." to discard changes in working directory)
   	deleted:    your-old-doc.md
   
   Untracked files:
     (use "git add ..." to include in what will be committed)
   	your-new-doc.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

8. Run the following commands to commit the updated files to your local Git repository. Here’s an example commit command to tell Git about one or more updated files:

   git commit -am "Fixed some doc errors."
   

   Here’s another example, which tells Git that you’ve added a file named your-new-doc.md, and then commits all changes include the added file:

   git add your-new-doc.md
   git commit -am "Added a shiny new doc."
   

   And another example, which tells Git that you’ve deleted a file named your-old-doc.md, and then commits all changes include the file deletion:

   git rm your-old-doc.md
   git commit -am "Deleted an obsolete doc."
   

9. Push the updates from your local branch to the corresponding branch on GitHub:

   git push origin your-branch-name
   

That’s it. When you look at your PR on GitHub, you’ll see a new commit listed among the comments on the PR. For example, the following screenshot shows two commits on a PR. One commit has the description “Updated for review comments”, and the other has the description “Added instruction to use different deployment name”:

When you view the files in the PR, you’ll see your changes incorporated into the latest version of each file. When the repository maintainers approve your PR, the changes will be merged into the repository.

Some notes:

• The word origin refers to the remote repository on GitHub from which you cloned your local repository when you first started working on it.
• You can use the following command to see which remote repositories Git knows about:

git remote -v

 

Using the GitHub UI to update the files in a PR

There are two ways to update a file in an existing PR using the GitHub UI:

• Access the file from the PR (described in this section).
• Access the file from your fork of the repository that you’re updating (described in the section below this one).

The first way is the most direct route to the file that needs updating, once you know how to do it.

To access a file from a PR:

1. Open a browser window.
2. Open your PR in GitHub, and click the Files changed tab at the top of the PR:
   
3. Click the three dots on the right-hand side of the window next to the name of the file that you want to edit, then click Edit file in the panel that opens up:
   
4. Make your changes in the editing interface that opens up.
5. When you’re ready, scroll down to the bottom of the editing interface. Enter a short description of the updates, and a longer description if necessary. Make sure the option is selected to Commit directly to the your-branch-name branch:
   
6. Click Commit changes.

That’s it. You’ve now updated the file in the PR. When you look at your PR on GitHub, you’ll see a new commit listed among the comments on the PR. When the repository maintainers approve your PR, the changes will be merged into the repository.

An interesting point is that other people can also add commits into your PR, provided they have authority to do so. Sometimes the repository maintainers may make an update to your PR before merging it, if it’s simpler to make the update than to explain it in a PR comment. (When you create the PR, you can grant or deny permission for the maintainers to make changes to the PR.) For example, the following screenshot shows a commit that I made into someone else’s PR, before merging the PR into the main repo. The commit has the description “Added specific link to Chainer page”:

 

Accessing your PR from your fork of the repository in the GitHub UI

The above section shows you how to access a file directly from a PR in order to update the file. As an alternative, you can go to your fork of the repository that you’re updating, and navigate through the files in the repository to find the one you want to update.

Usually, you work on a fork of the main repository on GitHub when you create a PR. If you use the GitHub UI to create the PR, GitHub creates the fork automatically for you, the first time you create a PR for a particular repository. The reason for creating the fork is that you probably don’t have update rights on the main repository. In the instructions below, I’m assuming that you have a fork of the repository.

To access a file from your fork of the repository:

1. Open a browser window.
2. Find your fork of the repository on GitHub. For example, if the repository name is “awesome-repo”, then the fork should be at this URL: https://github.com/your-github-username/awesome-repo.You can find your fork by going to the list of your repositories on GitHub. Click the dropdown arrow next to your profile image, then click Your repositories:
   You should see a list of repositories something like this:
   
3. Click the name of the forked repository that you want to update. You should see the details of the forked repository, including the files within the repository.For example, I clicked website to open my fork of the Kubeflow website repository. The Code tab shows the list of files within the repository:
   
4. Change to the branch that contains your PR within the repository fork. By default, the repository fork opens on the master branch. To change the branch, first click the Branch option:
   Then in the dropdown list that appears, select the branch that contains your PR. The branch name may be something like “your-username-patch-1”, or it may be something meaningful that you entered when you created the PR. For example, I need to select the v1-discussion branch to find my PR:
   Now you should see the same repository fork, with roughly the same files as you saw in the master branch. But the branch which you’ve selected contains all the changes you’ve made in your PR.
5. Click a file or directory name to navigate through the files within your fork of the repository. For example, I need to click the Content directory to find the file I’m interested in:
   
6. When you find your file, click the edit icon to edit the file as usual:
   
7. When you’re ready, scroll down to the bottom of the editing interface. Enter a short description of the updates, and a longer description if necessary. Make sure the option is selected to Commit directly to the your-branch-name branch:
   
8. Click Commit changes.

That’s it. You’ve now updated the file in the PR. When you look at your PR on GitHub, you’ll see a new commit listed among the comments on the PR. When the repository maintainers approve your PR, the changes will be merged into the repository.

How to download a PR from GitHub to your computer

This is a quick tip about a useful Git technique. It took me a while to figure this out when I first needed it. I was working on a pull request (PR) on one computer when I was in the office. Then I wanted to continue working on the PR from my laptop at home. I needed to transfer my work from my work computer to my laptop, using GitHub as middleman.

Another scenario for this technique is when you’ve used the GitHub UI to make some changes, but now you want to swap to command-line usage while in the middle of your PR. This could be useful, for example, if you find that your PR needs to include changes to more than one file, which is hard to do in the GitHub UI.

Prerequisites

You need Git on your local computer. See the Git installation guide.

I’m assuming the following things:

• You’re comfortable using command-line Git.
• You already have a PR that you’ve been working on, and you want to make a local copy of the PR so that you can update one or more files in that PR. (If you haven’t yet created a PR, you can follow this quick guide to working on GitHub, which I created for the Kubeflow open source doc set that I’m currently working on.)
• You’ve pushed your latest changes up from your other machine to GitHub, so that GitHub contains the latest version of the PR.

All you want to do now is to copy a particular PR down from GitHub so that you can work on it on this computer.

Clone the repository to your computer

If you’ve already cloned the GitHub repository to your local computer, you can skip this section. This would be the case if you’ve previously done some work on this repository and on this computer.

You need a clone of the GitHub repository on the computer you’re currently using, so that Git can track the changes you make in the repository. Usually, you fork the main repository on GitHub before creating a PR. The reason for creating the fork is that you probably don’t have update rights on the main repository. I’m assuming that you have a fork of the repository, and therefore your next step is to clone your fork of the repository to your local computer, as described below.

Note: If you’re working directly on the main repository rather than on your fork of the repository, then you should clone the main repository to your local computer.

To clone your fork of the repository onto your local computer:

1. 1. Find your fork of the repository on GitHub. For example, if the repository name is “awesome-repo”, then the fork should be at this URL: https://github.com/your-github-username/awesome-repo.
   2. Open a command window on your local computer.
   3. Run the following commands to clone your forked repository onto your local machine. The commands create a directory called git-repositories and then use HTTPS cloning to download the files:

      mkdir git-repositories
      cd git-repositories/
      git clone https://github.com/your-github-username/awesome-repo.git
      cd awesome-repo/

If you prefer, you can use SSH cloning instead of HTTPS cloning:

mkdir git-repositories
cd git-repositories/
git clone git@github.com:your-github-username/awesome-repo.git
cd awesome-repo/

You’re now in a directory called awesome-repo. If you take a look at the files in the directory, you should see some file- and directory names starting with .git, indicating that Git is tracking the files in the directory. You should also see the files and directories belonging to the GitHub repository that you cloned.

Download the PR to your computer

Follow these steps to copy the PR from GitHub to your local computer:

1. 1. Find your PR on GitHub and check the name of the branch that contains the PR. In the screenshot below, the branch name is gcpsdk:
      
   2. Go to the directory containing the repository on your local computer. The commands below assume that you’ve cloned the repository into a directory named git-repositories/awesome-repo:

      cd git-repositories/awesome-repo

   3. Run these commands to copy the branch containing your PR to your computer. In the commands, change your-branch-name to the actual branch name:

      git status 
      git checkout master 
      git fetch origin your-branch-name:your-branch-name 
      git checkout your-branch-name

That’s it. You’re now in the branch that contains all the updates from your PR. You can continue working on the files or adding new files. Remember to git commit and git push as usual, to copy your updates back up to GitHub.

Here’s an explanation of each of the above commands:

• git status: Run this command to see where you are and what the current status is of your files. You may have been busy with something that still needs tidying up before you can create a new branch.
• git checkout master: Go to the master branch to make sure you have a tidy place from which to create a new branch.
• git fetch origin your-branch-name:your-branch-name: This is the key command. It tells Git to copy the branch from GitHub (“origin”) and to create a new branch on your local computer with the same updates and the same name.
• git checkout your-branch-name: This puts you in the new branch on your local computer. This branch now has the same updates as the equivalent branch on GitHub.

Some notes for those who are interested

The above set of commands assumes that you want the branch name on your local computer to be the same as the branch name on GitHub. That’s most likely to be the case, but you can use a different local branch name if you need to. The command pattern is this:

git fetch origin your-origin-branch-name:your-local-branch-name
git checkout your-local-branch-name

The word origin refers to the remote repository on GitHub from which you cloned your local repository when you first started working on it. You can use the following command to see which remote repositories Git knows about:

git remote -v

First results for Season of Docs 2019 = first results ever

For the past year I’ve been working with colleagues to create and run Google’s Season of Docs program. It’s super exciting that the first results are now out. There are more results to come in the new year, when the long-running projects finish.

Congratulations to the technical writers and open source mentors who’ve successfully completed their standard-length projects and good luck to those who’re working on the long-running projects. Also a big thank you from me, to everyone who’s taken part in this pilot of the program, including those who had to withdraw from the program for various reasons. It’s been a privilege to receive all the feedback from everyone involved and to learn from the experiences of so many people.

Results for Season of Docs 2019

This year’s Season of Docs included a limited number of technical writing projects, as a pilot to measure how well the program would be received. There are 36 successfully completed projects out of the 41 standard-length projects that finished in December 2019. Eight long-running projects are still in progress, scheduled to finish in February 2020.

You can find further stats and details in the results announcement on the Google Open Source Blog and in the list of successful projects on the Season of Docs website.

The goals of Season of Docs are:

• Bring technical writers and open source projects together to improve open source documentation and thus to contribute to the excellence of open source products.
• Give technical writers around the world the opportunity to work in open source and to learn about open source processes, tools, products, and code.
• Help open source projects understand how technical writers work and what technical writers can contribute to the open source projects.
• Improve the overall experience of contributing to open source, by providing excellent documentation for new contributors.

Season of Docs 2019 participants come from round the world, including all continents except Antarctica.

What are the participants saying about their experiences so far? Here are a few quotations from the blog posts and reports that people have published.

• From technical writer Kartik in a blog post, Experience in Google Season of Docs 2019 with Apache Airflow:

I also started getting invited in the PR reviews of other developers. I am looking forward to more contributions to the project in the coming year.

• From technical writer Elena in the project report, Apache Airflow: Documenting using local development environments:

I’m deeply grateful to my mentor and Airflow developers for their feedback, patience and help while I was breaking through new challenges (I’ve never worked on an open source project before), and for their support of all my ideas! I think a key success factor for any contributor is a responsive, supportive and motivated team, and I was lucky to join such a team for 3 months.

• From technical writer Aaron, quoted in a blog post by open source mentor Olivier Hallot, The LibreOffice Documentation Team Announces the LibreOffice Online Guide:

My experience working on this guide was fantastic, and I would urge anyone interested in getting involved with open source to consider documentation as a first step. The Document Foundation’s documentation team in particular has a very well-established process and infrastructure for producing their products, and one of the only things I can think of that would help them is more volunteers.

• From technical writer Shaloo in a blog post about the GenPipes project, Giving it your all to Documentation!

Unfortunately, most of us who write software, think that documentation means simply translating what the software does in plain English. That is so not true. Documentation is more to do with how to use your cool software and solve real life pain points. Staying in touch with your user needs is of paramount importance, whether it is code that you are writing or the documentation for using the same.

• From technical writer Laurel in a post on the Ensembl blog, Ensembl is part of the first Google Season of Docs!

It has been both fun and interesting to learn about the Ensembl REST API implementation as well as to learn about what people who use the REST API need to get started.

• A tweet from GDevelop:

A brand new tutorial is now available for GDevelop, and we would like to thank @end3r for writing it as part of Google #SeasonOfDocs!

• A tweet from OSGeoLive:

Thanks a lot to @felicity_brand for supporting the #OSGeoLive project in #SeasonsofDocs 2019. She did a great job and improved our @osgeolive documentation a lot.

• From technical writer Edidiong in the project report, Modernize (rewrite) the VLC user documentation:

Overall, It was one of the best things that happened to me this year. I have been using VLC for as long as I can remember and the fact that I was able to contribute to the organization is an honor.

• From technical writer Pavithra in the blog post, My GSoD Journey – Part 3:

I like working with the Wikimedia community. I got to interact with some really amazing folks and the overall experience has been wonderful! Even though Season of Docs has officially come to an end, I intend to continue contributing and would welcome interested folks to join us.

• From technical writer Mister Gold in the project writeup, Report for the Bot Docs project:

At the end of the GSoD program, my Rocket.Chat mentors asked me to review a technical writer job posting they’d created. They said that the contribution I made to Rocket.Chat is invaluable and cannot be underestimated. They were so excited and impressed by this project that they have decided to hire a person who will be in charge of all the qualitative documentation updates. Rocket.Chat team confirmed that this is one of the greatest achievements of all the times in Rocket.Chat thanks to my work.

• From technical writer Muhammad in the project report, OpenMRS: Write Code, Save lives!

GSoD not only provided me with an opportunity to learn about open source but also to interact with some of the most wonderful people around the globe working enthusiastically for betterment of society and help create and most importantly maintain a Medical Record System completely free of cost for under-privileged as well as other users.
GSoD not only increased my knowledge about open-source and led me to meet exciting people, it also helped me to further enhance my technical writing and managerial skills…
I would love to continue working for OpenMRS and be an active member of the community.

• From technical writer Areesha in a writeup of the project, OpenELIS documentation for end users:

Google Season of Docs introduced me to open-source community. I realized how open-source projects offer multiple benefits to its users. Open-source systems provide more flexibility, security and transparency to the users as the system is continuously being reviewed and updated…
Writing technical documentation for a system that is implemented at such a wide scale and is a part of a global community made me learn so much about how the technical documentation is done in the real-world at the corporate and professional level.

• From technical writer Anna in a writeup of the project, How did Open Collective’s docs change in three months?

This community has welcomed me with open arms and I couldn’t be more grateful for that. Open Collective has found in me a contributor for life, and I hope to keep contributing for as long as I can.

• From technical writer Anne in the project writeup, The Ultimate Beginner’s Guide to NumPy:

If you’re interested in getting involved with NumPy or Google Season of Docs, I highly recommend it. If you’re new to open source projects, you might have a bit of a learning curve setting up your workstation, becoming familiar with NumPy’s contribution guidelines, and getting to know the ins and outs of .rst and Sphinx, but it’s so worth it. It’s definitely challenging if you haven’t done it before, but keep going. Once you get those details nailed down, you can start having real fun!

• From technical writer Alex in a writeup of the project with International Neuroinformatics Coordinating Facility (INCF), Technical Writer, Google Season of Docs 2019:

I’M STILL SMILING!

It’s well worth taking a look at all the project reports listed on the Season of Docs website, to see the scope of the projects tackled, the challenges that the technical writers faced, and how they overcame them. Every story is different!

Please do let me know of any posts I’ve missed, or if you’d like to add any experiences of your own. Add a comment on this post so that others can read it too.

Opportunities to contribute to open source

If you’re looking for opportunities to contribute to open source, these opportunities abound.

A note to avoid potential confusion: Contributing to these projects would be outside of the Season of Docs program, unless you’re already officially signed up to take part in the relevant long-running project in Season of Docs 2019, or you’re accepted into a future Season of Docs program in 2020 or beyond.

Some suggestions for finding a project to contribute to:

• In their project reports listed on the Season of Docs website, many of the technical writers describe followup work to be done.
• The open source organisations published detailed lists of ideas in their original proposals for Season of Docs. Many of these ideas are not yet addressed, because Season of Docs is only three months’ worth of writing!

There are more Season of Docs 2019 results to come

To the technical writers and mentors working on the long-running projects for Season of Docs 2019: Have fun, best of luck with your projects, and I’m very much looking forward to seeing the results in February!

To add to the celebratory nature of this post, here’s a picture of a tea tree flower spray which I came across while walking in the Australian bush: