Author Archives: Sarah Maddox

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.

Death of the gerund in technical documentation

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:

  • Markers, in the Google Maps JavaScript API.
  • Map Objects, in the Google Maps Android API.

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:

Refactoring overlays in the Google Maps JavaScript API documentation

One of my first big projects as a Google technical writer was to refactor the “overlays” part of the Google Maps JavaScript API documentation. In this post, I’d like to share the aims and results of the refactoring with you.

Did you know you can draw shapes on a Google map, just by creating an HTML page and including a bit of JavaScript? Or that you can add your own pictures and tiles to the map? I didn’t, until recently. The documentation explains the concepts upon which the API is based, and tells you how to use the classes, methods and events to draw objects and shapes on a map. The general term for this sort of shape or object is an “overlay”.

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

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:

Refactoring the Google Maps JavaScript API overlays documentation

After

Here’s the “after” image:

Refactoring the Google Maps JavaScript API overlays documentation

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.

Why refactor?

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. :)

Do you use singular or plural after “types of”

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:

A kookaburra looking goofy

Redirecting anchor links on web pages

I’ve recently discovered that it’s not possible to do a server-side redirect for anchor links on web pages! The reason is that the anchor part of the URL (the part containing the “#” and anchor name) is not sent back to the server. Not ever!

This is what happened to me recently: I had a long document, presented in one long web page. I decided to split it into two pages. A number of the headings had IDs which act as anchor links, and we know that external documents link to those anchors. I could fix any incoming links in our own documents, but not in the unknown number of documents out there on the world wide web.

This is a prime case for a redirect, or so you’d think.

An example

Let’s say I have a page called “Ice Floes“, and  I have the following HTML in my document:

<h2 id="penguin_joke">Penguins are cool</h2>
<h3 id = "introduction">Introduction</h3>
Did you hear the one about the penguins on an ice floe?
<h3 id="story">The story</h3>
<p>There are two penguins on an ice floe, 
drifting north into warmer waters. 
These penguins are very fond of each other, 
but they don't speak English very well.
Suddenly, with a terrific crack, 
the ice floe splits in half, right between the penguins. 
As they begin drifting apart, one penguin 
sadly waves a flipper and calls out, 
"Chocolate milk!"</p>

It’s quite feasible that there’d be incoming links to this document, like this:

Read all about the 
<a href="http://example.com/icefloes#penguin_joke">cool penguins</a>.

That’s called an “anchor link” because it points to a specific anchor in the page. In this case, the anchor is a heading ID.

Now let’s say I want to move the penguins to a page all of their own, called “Penguins“. I’d like to redirect the relevant links to the new page. So, dear server, please redirect all links of this form:

http://example.com/icefloes#penguin_joke

To something like this:

http://example.com/penguins#joke

Or even redirecting to the top of the new page would do:

http://example.com/penguins

So, what’s the problem?

The server can only redirect the link at page level. It cannot redirect incoming anchor links, because it never sees the anchor part of the URL.

For a link like this:

http://example.com/icefloes#penguin_joke

The browser only sends the server this:

http://example.com/icefloes

That’s right! The browser removes the anchor, stores it, and then puts it back when it needs it. Huh, who’d a thunk it.

Is there a workaround?

In my case, I’m lucky because the original page will still be there. So I’ve left a heading in the page, with a textual explanation and a link for people to click. Manual redirection.

I’ve also added a bunch of dummy, empty <div> sections with IDs, to cater for all the subheadings that used to exist within the section. This will bring all relevant incoming links to the same part of the original page, and people can click through to get to the right place. Ugly, but at least the readers will find their way to the right place.

This is what the updated, minimised section would look like, on the original “Ice Floes” page:

<h2 id="penguins">Penguins</h2>
<div id="penguin_joke"></div>
<div id="introduction"></div>
<div id="story"></div>
<p>Read all about penguins in the 
<a href="http://example.com/penguins">dedicated penguins document</a>.</p>

If I wanted to, I could also add explicit references to each section of the new page, but in my case that was too much text.

Client-side workarounds using JavaScript

If you can add JavaScript to your page, you can write your own redirects on the page. This question on Stack Overflow has some good answers.

Any more?

I hope this post is useful to someone who may run into the same problem as I did. If you have any more tips to share, I’d love to hear them.

A pretty flower from yesterday’s bush walk:

Redirecting anchor links

Follow

Get every new post delivered to your Inbox.

Join 1,394 other followers

%d bloggers like this: