Blog Archives

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.

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. 🙂

Google technical writer, 3 months in

A number of people have asked me what it’s like to be a technical writer at Google. I became a Googler three months ago. Now, as my manager remarked so eloquently, “the Noogler sheen is wearing off” and I’m settling down to regular Googliness. So, what’s it like?

That’s a hard question to answer. It’s empowering, scary, fun, frustrating, invigorating, tiring… All the usual things you’d expect in a new job, and then some. I love it. Most days. 😉

To answer the question, I’ve started by jotting down some random thoughts, followed by a “day in the life” ramble. I hope this gives you a good idea of what I get up to.

But there’s no typical tech writing role at Google

Google campus, Mountain View

Google campus, Mountain View

I’ve just returned from an internal Google technical writing conference called Burning Pen. It was awesome! Approximately 200 writers attended, from all over Google. We  congregated at the Googleplex in Mountain View, California. There were two days of sessions, running two streams all day each day. I met many great people and learned a lot about what other Google writers are doing.

It struck me that we’re all doing vastly different things: writing text on user interfaces (such as the labels on Google Maps), creating and curating content for Zagat reviews, developing API and developer-focused documentation (that’s my role), documenting internal tools for Google engineers and other staff, writing online help for Gmail and other consumer products, and more.

Random thoughts – what’s it like to be a Google technical writer?

It’s “technical”. I’m an API technical writer on Google Maps, which means that I show developers how to use the application programming interfaces (APIs) to integrate Google Maps into their own applications. As well as APIs, we document other developer products such as SDKs (software development kits) and other frameworks. We need to think like engineers, and understand what sort of thing external engineers will need to know about our products.

It’s fast, exciting, challenging, all-encompassing. My laptop is never far away, and I hack away at change lists between meetings, presentations, and bites to eat. While waiting for a plane, I fix a quick bug. While on the bus, I start triaging my email.

Team work is what makes the Google world turn. There’s always someone to turn to when I have a question. I get the impression I’ll be hacking and inventing with other people throughout my career here.

Like all technical writers, I like to feel that my work is valued. I definitely get that feeling here. I’m part of a team of people who rely on each other to get the job done. Documentation is a core part of the product, not an afterthought.

Work comes in small chunks. It’s a never-ending flow, but I get to tick things off regularly. For me, that’s very satisfying.

There’s plenty of opportunity to get in the zone and write. Yes, there are meetings and activities. Sometimes the “fire hose” of information can be overwhelming, but I learned quickly to filter the flow so that I get only what’s relevant to me.

Everyone has an opinion, and most people express theirs strongly. I sometimes need a loud voice and a touch of stubbornness to make my opinion heard.

Travel opportunities abound. I’ve been here three months, and already flown to Mountain View twice. My first visit was just a week after I started work.

There are good opportunities to make your mark. I’ve already presented a session at an internal Google conference.

More? Intensely interesting technologies. Vast scale. Innovation. The good feeling that I’m part of a company that’s making a difference in the world, and that cares very much that that difference is for the good.

A day in the life

I arrive early, around 7:30 in the morning. But I’m nowhere near the first to come in. People drift in at all times of the day – whatever suits them.

Bare feet, coffee, Big Red

Coffee machine

Big Red at Google Sydney

I drop off my laptop at my desk, and make a beeline for the coffee machine. On my way past a certain meeting room, I smile at a pair of bare feet. For some reason, there’s always a guy in that meeting room at that time of day, relaxing in a chair and chatting with someone via a Google Hangout. All I can see is his feet and ankles, because the rest of the glass is shaded. I’m guessing he’s talking to family somewhere on another continent, and very early in the morning is the best time to catch them.

Next stop Big Red, for a heart-punching cup of coffee. Big Red is the famous coffee machine in the Sydney office. Rumour has it that she was the first ever machine at Google Sydney. People treat her with pride and no little protectiveness.

Email, plans, mice and men

Armed with a cup of coffee, I read and respond to my email. There’s a lot of it. Email is our primary communication tool. I use Gmail’s special inbox categories to filter messages from people, notifications from various tools, and messages from special interest groups and forums.

Next I set out a plan for the day, in the full knowledge that things are likely to change and my plan will join those of other mice and men.

Tools, travel, chocolate

My primary tools for tracking work are the issue tracker and the code review tool used by the Google engineers. The documentation lives in the same repository as the code, and follows the same workflow. The software tools are in house and tend to be a bit idiosyncratic. But once you’ve got the hang of them, they’re satisfying to use.

My dashboards on the issue tracker and code review tools show me what I’m doing, what I’m scheduled to do, and what I’ve done recently. They also offer a good way of collaborating with other writers, engineers and product managers – especially with people who are on a different continent.

Meetings are also a big thing, to consolidate plans and designs and make decisions. We meet in person, via video conferencing, and via Google Hangouts.

Here’s a weird thing that happens often: I’ll talk to someone via video conferencing one day, because they’re a few thousand miles away, and then they’ll arrive at my desk the next day and pick up the conversation as if nothing happened in between. People are travelling all the time. They often don’t even tell you they’re about to hop on a plane. It’s just the way things are.

Back to tools. I also use Remember The Milk to remind me to do things like complete my weekly report, prepare for a weekly catchup meeting (which people call a “sync”), or buy a couple of chocolate fudge brownies from the nearby Pulse cafe on Friday. They’re to die for.

Words, code, markup

Must you be able to write code, to be a technical writer at Google? That’s a much-debated point. I think it depends on the role within Google. For my role, I’d say you’d be at a disadvantage if you couldn’t hack some code together.

Most of what we create is words. We write in HTML or Markdown, depending on our choice and on the existing format if we’re updating a document.

We also craft code samples. For a developer wanting to use our APIs and frameworks, a code sample speaks a thousand words. A technical writer will usually ask an engineer for help with the code samples, but we need to lick the code into shape and judge its usefulness as an illustrative example.

My first big project was to refactor some documentation for the Google Maps JavaScript API and build out the code samples. I blogged about the results: Refactoring overlays in the Google Maps JavaScript API documentation.

APIs, Linux, the colour purple

As someone who documents APIs, I get to play with code. I do a lot of command-line stuff, which is quite different from the wiki-based work that was the focus of my previous role. The tools I use now don’t have the power of the wiki in terms of integration with social media, rich text editing, and ease of use for non-technical people. But there’s a satisfying cleanness and simplicity to command-line input and text editors.

Did you know you can colour your Linux command window? Did you even want to know that? Heh heh, it’s the kind of thing I rejoice in now. 😉 Mine is currently purple with yellow text and blue highlights. I swap to a black-on-white window when I’m forced to use a Linux line editor. Most of the time, I use a text editor (Komodo) on my Mac to edit the documentation files. We’re free to use the tools of our choice, when it comes to text editors, IDEs, image manipulation tools, browsers, and so on.

Location, location, location

Sydney skyline

Sydney skyline

The Google Sydney office is in one of the most beautiful spots in the world. This picture shows the view from the balcony that surrounds the canteen.

The San Francisco office has a stunning outlook on Bay Bridge. The GooglePlex in Mountain View is restful, green, leafy and colourful. Those are the only three offices I’ve seen so far.

Three months, three offices. Not too shabby. I hope to see many more.

Food, food, food

Yes, the rumours you’ve heard are true. There’s food everywhere. We have a couple of “micro kitchens” on every floor. A micro kitchen is actually quite large, and boasts at least two types of coffee machine, a fridge full of drinks, shelves of snacks and fruit.

Each building also has a “café”, which is a deluxe staff canteen serving a full breakfast and lunch. Some cafés serve dinner too, for people who are working late. The lunch consists of a well-stocked salad bar, soups, a full cooked meal of a different variety every day, and at least two types of dessert. Amazing.

People talk about the “Google 15” – that’s the 15 pounds you gain when you join Google!

Did that answer the question?

Please feel free to ask questions by adding comments to this post. I’ll answer as best I can, as a Google technical writer three months into the role.

Report from a new Google technical writer

I’m a Noogler! Now that I’ve been at Google for a couple of weeks, I’m managing to drink from the fire hose without spluttering too much, and I’m learning my way around the technology. I’ve even published a “hallo world” documentation update.

So, what’s it like working at Google? It’s just plain awesome. The people are friendly, inquiring, bright, welcoming, intense, very very smart, and fun. The technology is coolth instantiated. What strikes me most is the scale of things. Google is huge, in every respect: in the numbers of Googlers, customers, and products, in the daring and innovation evidenced in the products, in the beauty of the office spaces, and in the welcome given to Nooglers like me.

I’ve spent the past two weeks doing orientation classes, meeting people, and learning how to use the in-house tools. I published my first documentation update. It was a small change to the page on usage limits in the Google Maps JavaScript API. To make the change, I had to find my way around the bug tracker, version control, editing, and publishing tools.

I’m based in Sydney, where much of the Google Maps development team hangs out. One week after starting work, I hopped on a plane to California, to meet the rest of the team. “Visiting the mother ship,” Googlers call it. The Google main campus is in Mountain View, about 60 kilometres south of San Francisco.

Have you seen the movie The Internship? I haven’t yet. I guess it’s a “must see” for me now!

This photo shows one of the Google buildings on the Mountain View campus. For more photos, visit my bookworm’s blog: Google in Mountain View, CA.

Google campus at Mountain View, CA

The Mountain View campus is big. It takes half an hour to walk from one end to the other. After doing that a couple of times, I plucked up the courage to try one of the Google bikes. Googlers pick them up and drop them off as needed. You can tell them by their colours:

A Google bike

At this point, there are two burning questions in every technical writer’s mind:

  • Will I have to start using US spelling and syntax? I guess so. 🙂
  • Do Googlers like chocolate? In answer to that, I’ll just say that my manager took the team to visit The Chocolate Garage in Palo Alto. What a great experience that was. We tasted such a variety of chocolates, from caramel-like smoothness to suprising saltiness. My favourite was the Madagascar 67% dark chocolate with habañero sea salt, made by Patric. As it touches your tongue, you feel the sharp salty bite of the chili. Then the chocolate kicks in, and the effect keeps changing until it leaves your taste buds feeling refreshed and ready for more.

Patric handcrafted chocolate

Want to know more? My bookmark, the Travelling Worm, has pictures of the Google campus and Mountain view: Google in Mountain View, CA.

Soon to be a Google technical writer

I have a bit of news to share:  I’m joining Google and saying farewell to Atlassian.

So long Atlassian, and thanks!

Friday 5 July was my last day at Atlassian. It was awesome being part of the Atlassian phenomenon for six years. A huge thank you to all Atlassians, and everyone in the wider Atlassian community: customers, add-on developers, experts, technical communicators and doc sprinters around the world! You’ve given me such great opportunities, and made me push myself into trying things that challenged me personally. (If someone had said six years ago that they’d spotted me doing any form of public speaking, my somewhat hysterical reply would have been, “Ha ha ha, nope, that’s some other Sarah.”)

Hallo Google

It’s time to go adventuring again. In a couple of weeks’ time, I’ll be a technical writer in the Developer Relations team at Google Sydney. This is tremendously exciting, and just a bit scary. That’s the best way to feel when starting something new.

Stepping into the sky

Stepping into the sky

I took this photo on a recent walk in the bush after a heavy rain storm. It’s a puddle reflecting the trees and sky.

%d bloggers like this: