Author Archives: Sarah Maddox
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
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
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.
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
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.
Actually, I’m fond of the gerund myself. I’m not seriously proposing we kill it, but I’d love to know what everyone thinks about using, or not using, gerunds in headings and page titles.
A gerund is an “-ing” word, like “adding” or “removing”. More specifically, it’s the “-ing” form of a verb when used as a noun. Most technical documentation uses gerunds in topic titles and page headings, like this:
- Adding a widget
- Deleting a widget
- Installing a widget
Examples of the traditional way:
Brave new world
We’re trying an experiment with short-form verbs in headings. Instead of gerunds, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page (using Ctrl+F, for example). It’s tempting to cite web searches as well, but any search engine worth its salt will find the stem of the word and return all results matching the stem.
Examples from our documentation:
At the moment, we’re leaving gerunds in the page titles (primarily for consistency across the documentation suite) and just changing the headings within the pages.
Others who’ve killed the gerund:
It had been a while since the last major overhaul of the overlays documentation. My team wanted to improve its usefulness to developers, by making it clearer and more readable.
Before my updates, the overlays documentation was all on one very long page. The page told you how to add polygons, polylines, rectangles, circles, markers, info windows, and various custom shapes to your map.
Here’s a “before” image. On the left is the list of pages that make up the documentation, with the selected page (“Overlays”) highlighted in red. On the right is the table of contents built from the headings on the page:
Here’s the “after” image:
So, now we have a short introductory page that explains the various types of overlays you can draw. Each type of overlay has a page dedicated to it.
There are three parts to the documentation:
- The guides to each type of overlay, starting on this page: Drawing on the Map.
- The interactive code samples, starting at Simple Markers and going up to Dashed Lines. I’m rather fond of Rectangle Events. You can move and resize the rectangle. An event listener spots that you’ve done something, and helpfully pops up an info window!
- The reference guide, which I did not change.
In this refactoring exercise, my aims were:
- Add more code samples, to help developers grok the API quickly.
- Employ content reuse for the code samples, so that we’re using the same piece of code embedded in the text and in the interactive samples, rather than copying and pasting code.
- Improve readability, by making it easier for people to grasp just one part of the API at a time, and to see the scope of the material they need to follow in order to draw a particular shape.
- Change the top-level page title from “overlays” to “drawing on the map”. We had a lengthy and interesting debate about what to call this page. “Overlays” was too obscure. (How many people would search for “overlays”?) We thought of “data visualisation”, but that seemed too grandiose. In the end, “drawing on the map” won the day. For now, anyway.
- Help people find the section they need, by exposing the different overlay types on individual pages and making them visible in the left-hand navigation panel.
- Improve SEO (search engine optimisation) by providing a meaningful title for each type of overlay.
- Experiment with short-form verbs in headings. Instead of gerunds in headings, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but in this case it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page.
Tackling a refactoring exercise like this is a very good way for a new team member like me to get to know the documentation and the APIs. :)
Would you say “two types of widget” or “two types of widgets”? In other words, should we use singular or plural after the phrase “types of”?
This is a real use case. In a code review this week, someone corrected my use of “types of widget”. People have varied and vociferous opinions. It’s intensely interesting, especially to technical writers.
Since I was a babe in arms, I’ve always used the singular:
“There are so many kinds of chocolate cookie! Which one shall I try next?”
“What are your favourite types of dog?”
To me this sequence just looks odd:
Pick one type of car.
Pick two types of cars.
Surely, if we can grant the English language a modicum of mathematical elegance ;) this should be correct:
Pick one type of car.
Pick two types of car.
So, why does the singular sound better to me? I think it’s because, when used after “types of”, the noun is acting as a concept representing a class of things, rather than a specific instance of the thing.
What do you think? Bring on the debate!
A kookaburra near my house: