Blog Archives

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.

AODC day 2: Optimising your Content for Google Search

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Joe Welinske, the presenter. Any mistakes or omissions are my own.

Joe Welinske presented the last session on Thursday, titled “Optimising the Googleability of Your Content”. The subject was search engine optimisation (SEO). Joe is really excited about this topic. He thinks it’s one of the most important skills for a user assistance expert to acquire. Potentially, it also offers a good opportunity for consultancy.

SEO is complex, but we need to learn about it. Joe calls it “embracing the beast”: If people are going to be using Google, then we want our material to come out at the top of the search results.

These are the topics he covered:

  • Get all your content on a public-facing server.
  • Learn about Google Search.
  • Learn about SEO (search engine optimisation).
  • Find out how to use other search engines.
  • Create a custom Google Search for your UA (user assistance) material.

Getting your content onto a public-facing server

This is the single most important thing that has to happen: Your content has to be on a public-facing server.

There are ways to mirror your internal content onto public-facing servers. Joe talked about a few of them. Ultimately, the best way may be to migrate all content to web-based standards.

Security issues when publishing content on the web

Many organisations keep their content behind the firewall, or have privileged content requiring login. Security is a very real concern. Moving to a public-facing server may be a big change for traditional content developers, and a challenge for organisations that have up to now kept their documentation hidden from public view.

Organisations need to take a detailed look at all the help components they provide and see what can and what can’t be published on a public-facing server.

We should be aware that our users are using Google anyway, and we should ask ourselves what these users find when they do a Google search for information on our products.

We could put together examples of Google searches, to show management what people will be finding, given that they can’t find our own documentation. For sure, people will be posting information about your systems to answer other people’s questions.

Google search indexing

Note that some content will not index effectively. Joe gave some tips on the type of content that Google can index well and the type that may cause problems.

Good candidates for Google indexing:

  • Web sites.
  • Web-based help, such as output generated from Flare or RoboHelp. Note that frames may make the content less favourable for indexing. Google has a hard time making sense of content in frames.
  • Eclipse Help is a good candidate, because it’s XHTML.
  • PDF is good, because Google has put effort into indexing it. Some PDF formats may be less effective.

What does not work well:

  • Microsoft Help (CHM and HLP) — This format has some HTML but is mostly locally-installed and uses a lot of proprietary code.
  • Apple Help, Oracle Help for Java and JavaHelp.
  • Flash — Google has done some work to be able to index text in Flash files, but images and videos not.
  • Almost any proprietary markup — Google has problems interpreting it.

Bottom line: The more open standards you use, the better off you will be.

What about loss of context?

When we put together online help systems and context-sensitive help, we have control over the path the user follows. But when the user comes in via Google search, we don’t have that control.

Some tips from Joe:

  • Provide navigation elements on all pages.
  • Add branding, so that people know that they have found your site and thus the official documentation.
  • Include the date last updated and the version of the application that the help covers.

Examples of SEO

Joe showed an example of a Google search he entered. He asked how to print a calendar in Excel. The first result returned was a link to Microsoft Office Online, telling you how to print a blank calendar. This was exactly what Joe wanted to do. What’s more, the content was an exact copy of what’s in the HTML Help provided with Excel, but laid out differently. So Microsoft has their SEO sorted out, and they are mirroring local help content in the web-based help.

Similarly, he entered a Google search for printing a Google calendar. Again, the Google web-based help was right at the top of the results. Google provides only web-based content, so they don’t need to support mirroring of content.

In contrast, when you search for “print an ical calendar”, there’s nothing near the top from Apple. So Apple needs to work on there SEO in this particular context.

How Google search works

It’s a combination of brute force and extremely clever technology:

  • Brute force: Google runs a gigantic server farm in Washington, that buys electric power directly from the hydroelectric dam nearby.
  • Extreme smarts for indexing information: Google has clever and secret algorithms for ranking content.

How does the ranking work?

Joe mentioned the following factors that influence the ranking of search results:

  • Fresh and real content — The search index recognises a page as offering a solid body of information, not just fake content. This is an area we technical writers excel at. Link farms out there put together random text and try to fool Google. But our standard documentation will match up as high quality.
  • Nomenclature — We use the right terms and the right labels in our documentation. If people use these terms in their searches, our content will quickly match.
  • Links pointing to our content — In Google’s eyes, links indicate what other people think of the information on the page. When many people link to pages, this makes it more likely in Google’s eyes that this is well-respected content.
  • Google Ads — There is some indication that your pages will be better indexed if they contain Google Ads.

Joe gave us these sources as guidelines on optimising your content for search:

Joe had a number of more in-depth hints on things like:

  • Including the “robot.txt” and “sitemap.xml” files.
  • Registering your site at “google.com”. (It’s free.)
  • Including metadata such as title, description and keywords.
  • And more. I’m sure Joe would be delighted to pass on this information if you contact him.

A tool to help analyse your pages for SEO

Of huge benefit is a tool called Go Daddy Search Engine Visibility. It goes through your pages and finds any search engine deficiencies. There are other tools that do the same thing.

Other search engines

Joe touched on other search engines, such as Yahoo and Bing. These are also important. Each has a separate registration procedure.

Getting other people to link to your site

Send people links to your content, such as sending links via email. Submit links to relevant sites. It’s a tough process and there’s no easy way to do it.

You can also think about community building:

  • Start a LinkedIn group.
  • Add YouTube videos with links in the metadata.
  • Add a Facebook fan page.
  • Tweet links via Twitter.
  • Encourage bloggers.
  • Supply RSS feeds.
  • Consider translated content, such as having even just a single page about your documentation, in different languages. Google indexes different languages too. Also, people who speak that language will at least learn about your documentation and your product. They can then click through to read the information in English.

Creating a Google custom search

It’s easy and free to register to create a custom Google search. Register your site. Google supplies you with the code you can use to put the search box onto your site. Google will index your site for you. Your search box will bring up results for your site only.

My conclusion

This was intensely interesting and full of information. I could not hope to capture everything that Joe told us. Thank you Joe! This presentation gave me a lot to think about and experiment with.

%d bloggers like this: