Sarah Maddox's Blog, page 27

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

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

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

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:

Android SDK
Confluence wiki

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:

Bitbucket
Splunk
Do you know of any more?

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:

After

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.

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:

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:

Penguins are cool
Introduction
Did you hear the one about the penguins on an ice floe?
The story

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!"

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

Read all about the
cool penguins.

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

Penguins

Read all about penguins in the
dedicated penguins document.

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:

Interviewed by STC Australia Chapter

The Australia chapter of the Society for Technical Communication has published an interview with me! It’s about building your personal brand, technical writing, and whether or not you’re emergent. Thanks very much to Tim Hildred for inviting me to be interviewed. It’s an honour. And thanks to Tim also for compiling such a great list of questions.

Moved – tips on Confluence editor and XML storage format

Graham Hannington’s advanced tips on the Confluence editor and XML storage format have moved to a new site: Advanced Confluence tips on the Knowledge Workers Wiki.

The pages were previously housed on the wiki associated with my book, Confluence, Tech Comm, Chocolate. That wiki is now shut down, but the tips live on!

What tips?

These are the tips currently available:

Bypassing the Confluence rich text editor interface
Converting Confluence rich text editor content to wiki markup
Converting Confluence storage format XML to wiki markup
Editing Confluence pages in an external validating XML editor
Validating Confluence XML storage format

Promoting heading levels
Searching Confluence storage format XML for content or markup

Adding custom toolbar buttons to the Confluence rich text editor with Greasemonkey

Thanks

Many thanks to Martin Cleaver at Blended Perspectives, for hosting this treasure trove of tips. And many thanks also to Graham Hannington, for all the work and insight he’s put into investigating and documenting the tips.

Looking for a Confluence wiki to play with while reading the book?

If you’re reading, Confluence, Tech Comm, Chocolate, you may want a wiki to try out the techniques described in the book. For the first 18 months after publication, a Confluence, Tech Comm, Chocolate wiki site was available for readers to experiment with. That site is no longer available. If you like, you can get a free evaluation licence from Atlassian, to experiment with Confluence.

Flowers from a recent walk in the Australian bush. Early spring.

How to become an API technical writer

A fellow technical writer asked me recently if I had any tips about becoming an API technical writer. That’s someone who writes developer-focused documentation, describing the application programming interfaces (APIs), software developer kits (SDKs), and other tools that developers use to make one application talk to another. This post has some tips I can share. If you have any more ideas, I’d love to see them too.

My 2c: In doing developer-focused documentation, there’s the writing side, the technology side, and the “attitude”.

The writing

The writing side isn’t all that different from user-focused technical writing. You’re telling people how to use something. In this case, it’s an API or SDK or other tool.

A while ago, I asked some respected developers about their favourite technical documentation sites. The results are in this post: What developers want. There are some useful links in the post and in the readers’ comments. Another post describes a project to build a developer documentation wiki, and also has some useful links and tips.

Stack Overflow has some good information about writing API documentation. Try a search, and pick the answers that suit you. For example, Best ways to document use of an API and What is the best way to document an XML-RPC API.

The tech

On the technology side, you need to know the basics of web technology: HTML, CSS and JavaScript. W3Schools offers some good courses, free of charge, to get you started, or refresh dormant knowledge.

If you’re aiming to work at a particular company, find out what technologies their developers use, and get to know those well. It’s also good to pick a widely-used programming language, such as Java or C++, and do a basic programming course so you know what it’s all about.

Different companies have varying requirements for their API technical writers. In some companies, the bar is set quite high – you’ll need to be able to write your own code samples and review the code written by the developers. In other companies, it’s enough just to read code.

The attitude

A developers’ technical writer needs to love APIs and SDKs. As far as you are concerned, they are the future of the universe. Immerse yourself in the concepts, and fly with the buzz words. Know what the cool kids are doing. Play with the technologies.

Hacker News (HM) is a popular discussion site for devs. Drop in regularly on the Hacker News Daily, to see the most popular topics of the day. HN has a good mix of tech topics, engineering of all sorts, political, social, and more. At first the tech topics will be foreign to you, but after a couple of weeks you’ll start pulling technologies together nicely.

Experiment with some APIs – Google Maps, for example

There are some great APIs to play with. Getting to grips with one or two will teach you about APIs and their accompanying documentation.

For example, try the Google Maps JavaScript API. Of course, I have a soft spot for it, because I’ve just started working on the documentation. But I think it would make a good API to start with. It’s fairly approachable: if you use Google Maps, you’ll recognise the features offered by the API. And you can use the API just by building an HTML page in a text editor, and copying and pasting the sample JavaScript from the tutorials. It’s fun and satisfying to see your very own map taking shape, with the full power of Google Maps as a base.

More tips?

How about you – do you have any advice for up-and-coming API technical writers? For example, I tried to think of a good book to recommend, but nothing sprang to mind. All ideas welcome!

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.

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:

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.

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

Guide to operating a safe

I spotted this “how to” guide in a hotel this weekend. It tells you how to use the mini safe in your room. My first thought was, “Wow, that’s a long guide for a simple procedure”. Then I started reading it, and my thoughts changed to, “Wow, what a complex procedure”. Out of interest, I followed the steps. They worked like a charm. Aside from inviting debate about the use of quotation marks the guide is interesting as an example of a document that makes possible a task that would otherwise have been unfathomable.

This is the safe, with a partial view of the guide at bottom right:

Here’s a closer view of the keypad:

This is the guide:

For easier reading, here’s the guide in text form. I’ve changed all text to sentence case, but left the punctuation, spelling and wording as is:

To operate safe

1) Press “red” buttonbehind safe door. A “yellow” light will come on indicating you can now reset your new code.

2) Input your new code and press “A or B” the safe will beep if the code has been accepted. However if the “yellow” light and the buzzer beeps 3 times the code is invalid and you will need to start again.

3) Once your safe has been re-coded close the safe door and turn the knob “anti-clockwise”.

4) To open your safe: input your code followed by the “A or B” button and turn the knob”clockwise”.

The first step is to find that red button. After a slight hesitation, I opened the safe, and saw this handy contextual help:

The angle was difficult and the lighting bad, but I could just spot the button on the inside edge of the door:

The camera’s flash illuminated the scene:

My only other hesitations were:

Where is the yellow light?
Where is the “A or B” button?

After pressing the red button, I spotted the yellow light at top right of the keypad:

For the “A or B” button I chose the “A” at bottom left, which worked just fine.

So, a few typos, but a good guide that got me safely through a tricky procedure.