Blog Archives

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.

A lightning talk on doc sprints

At the upcoming Collaborations Workshop 2019, run by the Software Sustainability Institute UK, I’ll be presenting a lightning talk on doc sprints. One slide, three minutes. Wow, that’s a short time for a big topic. 🙂 So I decided to blog about my talking points as well as presenting a shorter version of them during the lightning talk.

Here goes: These are my talking points for a lightning talk about doc sprints.

What is a doc sprint?

A doc sprint is an event where people get together to write documentation and, often, code.
The sprinters work together for a given period of time, usually two to three days, on a specific set of documentation.

Why run a doc sprint?

A well-organized doc sprint produces excellent results. The sprinters create new tutorials based on the needs you’ve identified. They fix doc bugs based on the hot lists you’ve put together. They learn about your product and your community, and with any luck they’ll continue contributing to the project after the sprint is over.

Why do people take part?

People have various reasons for taking part in a doc sprint. They enjoy sharing their skills and helping other people. They appreciate the opportunity for contact with other members of the development team and the community. They like the recognition that comes with having their contributions accepted into your documentation site. They like fixing stuff.

How do you run a doc sprint?’

If I were doing a full presentation rather than a lightning talk, this would be the largest part of the presentation. In a nutshell:

  • Prepare well in advance: start two to three months before the date of the sprint.
  • Think carefully about who to invite.
  • Prepare a list of the docs you want written and the bugs you want fixed.

Praise and prizes

It’s important to recognize the work people have done, and the time they have spent contributing to your documentation. There are a few ways you can reward people. Write a blog post listing the work done and the authors’ names. Link to their favourite social media account, so that people know who they are.

Provide people with stickers or badges showing the name of the doc sprint. Provide a T-shirt if your budget allows that. People love swag.

More tips

Here are some more hints that I won’t have time to mention in a three-minute lightning talk:

  • Pick a time when most people are less busy than usual – for example, the start of a quarter, or the start of a year, before deadlines start kicking in. Avoid conferences and other eventts that you know your target community will be involved in.
  • Invite everyone – software engineers, support engineers, product managers, technical writers, UX designers, and more. They’ll all have something to contribute to the sprint, whether it be defining the list of documents that need writing, reviewing the docs, or developing the docs.
  • Be ready to do lots of reviews during the sprint. As the tech writer, you probably won’t have time to write any docs yourself. It’s best to get as many of the reviews done during the sprint as possible. When the sprint is over, everyone moves on to other things, and getting reviews finalised becomes more difficult.
  • Prepare hot lists of the things you want fixed, or a wish list of the docs you want written. Consult stakeholders before the sprint, to refine your hot lists.
  • Create a sprint guide. Keep it short and simple. Include the date of the sprint, the time of the sprint kickoff meeting, people involved, links to hot lists, where to send reviews.
  • Provide a guide to updating the docs.
  • Share the results via reports, both during the sprint and in a sprint wrapup. If there’s no report, it didn’t happen.

Here are some detailed guides I’ve created after running a few doc sprints:

Emoji tree trunk

Not related to doc sprints specifically, except that I hope your doc sprint will feature many smiling faces!

Upcoming meetup in Sydney: open source, change in the digital age, developer docs, and you!

The Write the Docs AU community is holding a meetup in Sydney on Thursday, 21 February. 

If you have a view on technical documentation, you’re invited!

Date and time: Thursday, 21 February 2019, at 6pm – 7:30pm

Location: Google, 48 Pirrama Road, Pyrmont (map)

Sign up on Meetup.com

There’s pizza and the opportunity to chat with friends old and new. Then we’ll move quickly to the exciting lineup of talks:

Building awesome technical writers from open source communities

Speaker: Cameron Shorter

The secrets behind inspiring an open source software community to write awesome docs. A story about how we initially got it wrong before improving. (Spoiler – technical writers play a cornerstone role).

Cameron is a software developer, business analyst, open source community builder, and accidental technical writer.

Tech Writers as Agents of Change in the Digital Age

Speaker: Priya Varghese

As we race through the digital era, swiping away one app after another, there are numerous companies and organizations out there that haven’t yet strapped themselves in properly for the digital transformation roller coaster.

Priya Varghese (a technical writer) talks about how technical communicators can become agents of change (in a disguised double role), with the key skills, advantages and vantage points to successfully help their teams on board the digital transformation journey.

Getting started for developer documentation

A lightning talk.

Deepti Korwar, a technical writer, talks about the necessary skills and available resources for writers considering to move into developer documentation roles.

Lightning talk 2

This five-minute spot is open. Suspense! Someone may stand up and speak impromptu at the event.

See you there!

Applying for the Google Sydney tech writing role? Some hints from me

Google currently has an open role for a technical writer in the Sydney office. See the job posting. Here are a few thoughts, from me as a tech writer at Google in Sydney, on how you can prepare to apply for the role.

A note up front: These hints come from me personally, as a tech writer at Google. I’m not the hiring manager for the open role, and following these hints won’t assure you of a successful application.

The advertised role is for a technical writer in the software engineering area. Let’s dive straight in!

Resume, samples, writing exercises

For a tech writing application, the resume is super important. Treat your resume as the first writing sample you’ll submit to Google. Make sure it’s clear and consistent. For example, it doesn’t matter whether you use US, British, or Australian spelling, provided you stick to your choice throughout the document. The same applies to punctuation of bullet items—just be consistent. Avoid unnecessary capital letters, check your spelling… you know the drill.

If your resume shows the skills and experience that suit the role, Google will ask you to submit some writing samples and complete a set of writing exercises.

For the writing samples, make sure you send in the work that demonstrates sound tech writing principles. If you have any code that you’ve written and that you can link to from your resume (for example, on GitHub), that’d be useful too. Even if the code is something you put together while learning a programming language or experimenting with an API, that’s good.

You may be asked to complete some specific writing exercises. Take your time in completing the writing exercises. Apply your tech writing soft skills as well as standard tech writing principles. A good tip is to sleep on it before you submit the exercises. Come back the next day to take a fresh look at what you’ve written. Focus on the intended audience for each sample. Include comments noting any extra information you’d ask for if you were writing the docs in a real work environment.

Interviews

Once your first interview has been scheduled, you’ll be able to chat to the Google hiring representatives and they’ll give you plenty of information about the interview process.

Usually there are a number of interviews, some by phone and some in person. You’ll speak to people in different roles, which may include tech writers, engineers, developer advocates, managers, and more.

A good hint for the interviews themselves is to remember you’re a tech writer, with the skills of a tech writer, and those skills are not the same as those of an engineer. Your interviewers may be tech writers, engineers, or managers. So, ask questions during the interview as if you were interviewing an engineer or a product manager. Make it clear to them that that’s what you’re doing.

You can find more tips to help you prepare on the Google Careers site.

General preparation

During the leadup to the interviews and throughout the process, read widely to keep programming terminology and concepts on the tip of your tongue. Read as much as you can about web programming and any other aspects of programming that interest you. Explore the world of APIs in full—be aware of Android and iOS APIs, JavaScript APIs, etc, as well as REST APIs.

It’s a good idea to become familiar with Google developer products, docs and style, to show your interest in the role. Be aware of the Google Developer Docs Style Guide, browse the Google Developer Docs site and the Google Cloud docs.

Coding

People often ask about the coding requirements for a tech writing role at Google. It’s a vexed question, and you’ll receive different replies depending on the role. This section of the post takes up a lot of space—arguably too much in proportion to its importance—but I’d like to give the best hints possible.

For this role the expectation is that you can comment on things like consistent and meaningful names for methods and classes, good use of code comments, and other aspects of code readability. In an interview, you should be able to ask the interviewer questions about a piece of code, as you would if you were planning to document it.

The job description mentions a few programming languages. It’s a good idea to focus on one (I’d recommend Python if you don’t already have a favourite) and do some studying in the leadup to the interview process. In fact, when I applied I continued studying throughout the process to keep the concepts and skills in focus. Life is busy, and it’s easy for some things to drop down into the less-easily accessible areas of our brains! This Python course is a good one.

To the best of my knowledge, you shouldn’t have to solve a problem in code during the interview. At most, you may be asked to write pseudo code. I’ve heard various reports about whether you need to do whiteboarding of simple code during an interview. I think it depends on the interviewer. I did have to do some whiteboard coding in one of my interviews, and I totally messed it up because I was extremely nervous. I still got the job. I did much better on the conceptual questions (what is a class, what is inheritance, what does “closure” mean to you, and so on).

For this particular role, we’re looking for someone who’s willing and able to continue learning about software and code. It’s not necessary to have in-depth coding skills. If during an interview you’re asked to do some coding that’s beyond your current skills, fall back to discussing the key technical concepts involved and to interviewing the interviewer about the requirements and goals of the application / system.

My top hints

Be passionate about tech writing. Let the interviewers see that you enjoy the role of tech writer, and be ready to tell them why. If you’re active in the tech writing community, let the interviewers know that. Mention any opportunities you’ve had to mentor other tech writers or students.

Be yourself. 🙂

%d bloggers like this: