Blog Archives

How to start a YouTube video at a given point or time

Here’s a tip that technical writers will love! You can start a YouTube video at a specific point, by including the time-from-start in the URL or as a parameter in an embedded video.

Let’s say the sales team has produced a video introducing a number of new features in your product. Or an engineer has covered a suite of classes in an API. As a technical writer, you are writing about just one of those features, or just a subset of the classes. So, you need to start the video at the right point. Otherwise you’ll lose your readers!

In the examples below, I’ve used an excellent video from Chris Broadfoot, a Google engineer who is showing developers how to add spiffy map features to their Android apps using the Google Maps Android API utility library. I’m currently writing the documentation which focuses on just one of the utilities Chris covers: the Bubble Icon Factory. Does that sound like fun? It is! Watch the video to see what it’s about. :)

Using a URL to start a YouTube video at a specific point

Add the ‘t‘ parameter with a value in minutes and seconds. For example, this YouTube URL starts the video one and a half minutes into the story, where Chris talks about bubble icons:

http://youtu.be/nb2X9IjjZpM?t=1m30s

Starting an embedded YouTube video at a specific point

Use the ‘start‘ parameter and specify the number of seconds from the start of the video.

This is the code to embed a video using an iFrame, and start it at the 90-second point. Please assume the following code is within an HTML iframe element:

width="560" height="315" src="//www.youtube.com/embed/nb2X9IjjZpM?start=90" frameborder="0" allowfullscreen

Because this blog is on WordPress, I’ve used a WordPress macro to embed a video on this page and start it at the 90-second point. This is the code:

youtube=http://youtu.be/nb2X9IjjZpM?start=90

And here’s the result:

More parameters

The YouTube documentation has a list of other useful parameters, including ‘end‘ for stopping the video at a given time, and ‘rel‘ for showing or suppressing the list of related videos when yours stops playing.

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:

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!

Invitation to a webinar about doc sprints tomorrow

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.

Invitation to a webinar about doc sprints tomorrow

Oh, just so you know, it will be 6am here in Sydney. I’ll watch the sun come up while presenting the session. :)

Follow

Get every new post delivered to your Inbox.

Join 1,397 other followers

%d bloggers like this: