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:
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 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.
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.
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.
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!
Along with the Society for Technical Communication (STC) I’ll be presenting a webinar tomorrow, about doc sprints. It would be great if you can join us!
The webinar is titled Doc Sprints: The Ultimate in Collaborative Document Development. It’s full of information about planning and running a doc sprint, and how doc sprints are useful in developing the documentation our readers need.
As well as information gleaned when running doc sprints at Atlassian, I’ve included stories and tips from doc sprinters around the world: Anne Gentle, Swapnil Ogale, Ellis Pratt, Katya Stepalina, Andreas Spall, Jay Meissner, and Peter Lubbers. The stories are what make a good doc sprint awesome.
How to sign up for the webinar
Dates, times, and registration details are on the STC site: Doc Sprints: The Ultimate in Collaborative Doc Development.
Oh, just so you know, it will be 6am here in Sydney. I’ll watch the sun come up while presenting the session.
Our team at Atlassian has just started presenting a series of workshops for other Atlassians, on how to write effectively. People are very appreciative of the knowledge they gain in the workshops. In turn, we technical writers learn a lot from the participants. We see how much other people value our own skills. And we get a fresh look at writing and documentation, from another viewpoint. What’s more, the workshops are fun and invigorating. Added value all round!
I’m sharing the idea and content of the workshops in this post, because we’re finding them so valuable. It’s very rewarding as a technical writer, to see how much people value our knowledge and skill. It’s also interesting to see how much they appreciate a guiding hand in what we consider the very basics of writing a technical document.
Sometimes we forget just how much we know.
The format of the workshops
Each workshop takes the form of a one-hour session:
- Lecture – see the material below. Questions are welcome at any time.
- Questions and wrapping up.
- Assignment of pages and posts for the workshop participants to work on at their leisure.
Before the session, the technical writer liaises with the manager of the team about to attend the workshop. We discuss the primary focus, and find out whether the team has any current plans to write documents or blog posts. Just recently in our organisation, a number of teams have put strategic initiatives in place to write and blog more. So our workshops come at a good time.
We also ask the participants and team leads to think of documents that need writing, so that their post-workshop assignments can be real documents.
After the session, the participants complete their assignments and choose one of the available technical writers to do a review. The review is a half-hour one-on-one chat, focusing on the document and any further questions the participant may have.
Kicking off the workshop
[The next few sections in this post contain the content of the workshops. The content is on a page on our internal wiki, which the technical writers use as a basis for the workshop. Participants can also use the page as a reference after the session.]
In this session you’ll learn how to write documents that people will find, read, and get what they need from. The aim is to provide a practical guide to help you get started quickly, and to put you in touch with the technical writers who can assist with reviewing your work.
We cover two types of document:
- A “how to” guide on the corporate intranet.
- A blog post on the corporate external blog.
Getting started on a document
How do you write a document?
One word at a time… not!
The big picture is the important thing.
- Sit back, think, and plan the document before you start.
- While writing, if the words don’t come, make a note and continue writing. Preserve the big picture. Come back later to fill in the gaps.
Talking to your audience
Who do you want to read the document? Who are the people you’re writing for, and what do they already know?
- Think about those people carefully. Make a mental picture of a person who has the characteristics of your target audience.
- Use that imagined person to make all decisions about your document.
- When in doubt about wording, speak to the imagined person out loud. Write down what you said. Write it down immediately, while it’s fresh. [I usually tell an anecdote here, about how some writers stick a picture of a person on their computer monitor, and talk to that picture.]
- If there’s more than one audience, consider writing a separate document for each audience. For example, consider separate documents for administrators and ordinary users.
The structure of a page
[The aim of this diagram is to illustrate that a page should have a number of headings, with short bits of text between them. After a quick look at the diagram, we discuss the sections in more detail below.]
State the purpose and audience at the top
Tell people who the document is for, and what it will help them do. This will let them know if it’s the right document for them.
Separate the concepts (“what” and “why”) from the task (“how”)
Some people already know the concepts. They’ll skip past that bit and go straight to the “how”. Other people know how to do something – they’ve found the right spot in the user interface, or found the right form on the intranet. But they want to know why they should do it, or what it means.
Split the content into easily-digestible chunks. Keep them short.
Use plenty of headings, so people can find the chunk they need. Research shows people’s eyes jump from heading to heading as they skim a page.
Lead your reader by the hand
Give clear, numbered steps. Don’t skip any steps.
People have come here because they’re stuck. Don’t worry, they’ll go away again as soon as they’ve got the idea.
Add related topics and/or next steps
Send the readers away immediately if they’re in the wrong place. After that, don’t send them away until you’re sure they’ve got what they need. So, keep links to a minimum in the main portion of the page.
- At the top: In the section about purpose, add links to documents the reader may need instead of this one. For example, if you have separate documents for administrators and users, link from the one to the other.
- At the end: Put related topics and next steps at the end, when you’ve finished with your reader.
Examples from our product documentation
[At this point, the workshop participants have already absorbed a lot of theory. It's a good time to show them some examples of good and bad design. Use these examples as a discussion point. Ask the participants what is good or bad about each page.]
- Our current style is to put the related topics at the top on the right, instead of at the bottom. We’re discussing a change, because the design doesn’t work too well on mobile devices.
- Instead of a warning macro, we’ve used a panel (uncoloured) with an exclamation icon. There’s some discussion about coloured panels, and whether people skip over them when reading a page. See the references to “banner blindness” in the resources section below.
- [This is a good place to break for a quick chat about banner blindness. Find out what the workshop participants think about it, and how they themselves read a document.]
[This is a page that has grown organically, with contributions from many people over a long period of time. It's had a revamp in the latest version of our documentation. The link points to an earlier version.]
- No clear step-by-step flow.
- No indication of what each section is for, and whether you need to do them all.
- Other comments? [This is a good place for discussion amongst the workshop participants.]
Language and style
[This section contains a few key tips on language and style - the bread and butter of technical writers, but not necessarily well known by other people.]
Keep it short and simple
Use simple words and short sentences.
Use active voice rather than passive
[Explain the difference between active and passive. Hold a bit of a discussion here. This is a difficult concept for many people.]
- Passive: The chocolate was eaten by the technical writer.
- Active: The technical writer ate the chocolate.
Why use active voice? It’s shorter. And passive voice can be confusing, because sometimes it doesn’t say who must do what. Imperative (command) is even better, when appropriate.
“Your browser must be configured to xxx.”
Reader thinks: OK, so I’ll assume someone has already done that for me when setting up my machine.
“Configure your browser to xxx.”
Reader thinks: OK, I’ll do that now.
Clarify technical terms and abbreviations
Explain important concepts at the top of the page.
Spell out each abbreviation the first time you use it on a page. For example:
If you’re using IE (Internet Explorer), ….
…with regard to Workplace, Health and Safety (WHS).
The title is your most important tool for helping people find your document. This is especially true on a Confluence wiki, where people use the quick search a lot. The quick search is based entirely on the page title.
- Put the key information at the beginning of the title.
- Make the title describe the purpose of the document.
How to go about writing a page
[After quite a bit of conceptual and theoretical information, the workshop participants welcome a practical guide at this point.]
Step by step:
- Decide on your audience.
- Write the purpose.
First write it for yourself, then refine it for the audience. This helps to form the content of the page.
- Write the title.
- Outline the document by creating the headings.
- Fill in the details.
Keep each section short.
- If unsure, or struggling to find the right words, make a “TO DO” note and continue. Come back later.
Hint: I use “xxxxxxxxxxxxxx” instead of “TO DO”. It’s quick to type, strangely satisfying, easy to search for, and stands out when I’m reviewing the page. [This bit often leads to some animated discussion amongst workshop participants. Some of them already do something similar. Others love the idea, and smile with delight.]
- Review the content yourself:
- Have you included everything you intended to include?
- Can you cut anything out?
- Should you split the document?
- Is your language and tone right for the audience?
- Ask someone else to review the page.
As any writer will tell you, it’s impossible to review your own work. Your brain knows what you wanted to say, and that’s what your brain will see even if that’s not what’s written.
- If possible, do some user testing.
Grab a colleague from a different department. Get a different perspective!
- Watch the page, and update it based on comments.
More about structure, at space level (specifically for Confluence wiki)
[It's time for more theory.]
We’ve already talked about the structure of page. The structure of your space also important. People often need to browse to see what’s available. Perhaps they don’t know what to search for, but they do know the general area they’re in.
Scenario: Jack searches for “proxy” and finds a page. But it’s not the one he wants. So he looks at the nearby pages.
- Group related topics under a common parent.
- Use the Documentation theme to show the space structure.
Making sure people find your page
- Structure of a wiki space
- Page titles
- Links to related topics
In addition to the above, let’s look at SEO (search engine optimisation) both internal (on the intranet, for the Confluence search engine) and external (on the corporate blog, for Google etc).
These are the key points for making sure people find your page or post:
- Make the title meaningful, with important words near the beginning.
- Make sure the URL contains real words.
If you are blogging on Confluence, don’t use special characters like “?” in a page title, because the resulting URL will not contain words.
- Decide the key words for your post. These are the key concepts, and the ones the people are likely to look for when searching.
- Put your key words at the top of the post, in the introductory paragraph.
This ties in well with our structure, where the first section contains a introduction and a summary of the story.
- Put your key words in the headings in your post.
- Templates and blueprints – make some of your own.
- Use the spell checker in the browser.
- Gliffy is great for simple diagrams.
- Writing is a creative process, and it keeps happening even when you think you’ve stopped!
You’ll find yourself thinking of stuff to add to your document at odd times. While walking in the bush. Or in the middle of the night. Make a note. Email yourself. Put it on Remember The Milk. Whatever works. Such ideas are gems. Don’t lose them.
- Optimise your page for people using mobile.
No section and column macros (on Confluence wiki).
Short sections with lots of headings.
- Limit the number of note- and warning-boxes to a maximum of two per page. Using more than this can indicate an organisational problem in the text.
Writing blog posts
[This is just a summary. We have another workshop that focuses on blog posts.]
Your blog post is likely to be technical, so the process of writing it has much in common with writing a technical document.
Here are some quick pointers:
- Maintain a character in your blog, so that people can start seeing it as a friend. Blogging is a social activity. Be yourself! Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
- If you’re writing on the corporate blog, ask for guidelines about the tone and style to use.
- Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.
- Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.
- Add structure to the content. Yes, even in a blog post. Put headings in the post itself. Split the information into easily-readable chunks.
- Give plenty of factual information, preferably hard-won. That’s what people value. Code samples and screenshots are great.
- Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
- Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.
- Kurt Vonnegut:
Here’s my all-time favourite: Kurt Vonnegut’s How to Write With Style.
The best thing about Kurt’s guide is that it illustrates his principles so perfectly. This excerpt is from the section called “Sound like yourself”:
…lucky indeed is the writer who has grown up in Ireland, for the English spoken there is so amusing and musical. I myself grew up in Indianapolis, where common speech sounds like a band saw cutting galvanized tin, and employs a vocabulary as unornamental as a monkey wrench.
This bit is pretty cool too:
Pity the readers
- Avoiding framed and decorated text boxes:
- [Link to your corporate style guide here.]
That’s the end
In designing the content of the workshop, my aim was to give the participants as much practical guidance as possible in a short space of time. I picked the top things we technical writers know, about how to make a document work.
To add variety to the one-hour session, I chose a mix of theory and discussion sections. The sessions to date have been lively and interactive. We ask participants to complete a feedback form a week or so after each session.
The actual writing happens after the session, in the participants’ own time. They can then request a one-on-one review with a technical writer, before publishing their document either internally or for the whole wide world. Participants have expressed their thanks and said the content is useful, and have indicated a wish to attend a follow-up session.
What do you think of this type of workshop, and its potential as a way technical writers can add even more value to our organisations that we already do? I’d love to hear if you have run something similar within your own organisation too.