Blog Archives

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.

Bring your chocolate recipes to the Confluence Tech Comm Chocolate wiki

Do you have a favourite chocolate cake, a chocolate drink to die for, or the best chocolate sludge in the world? 🙂

If you’d like to share your recipe and play with Confluence wiki at the same time, I’d love to see you on the wiki!

Add your chocolate recipes here.

If you’ve baked the cake from the recipe in the book, I’d love to see a photo of it! You can add a photo on the wiki too.

Pre-orders of my book available at reduced price

If you’re thinking of buying my book, now is a very good time. 🙂 Pre-ordering is available at Barnes & Noble, and they’re offering a price of just $26.96 (reduced from $39.95) for a few days.

Update (Saturday 5:15pm in Sydney): The price is now $21.57! I don’t know how long the offer lasts.

Update (Sunday 19 February): There are some problems with the Barnes & Noble page for the book – there is currently no pre-order or buy button at all. In addition, some people have received messages from B&N saying that their orders have been cancelled. Richard Hamilton at XML Press  is investigating. I’m so sorry about the confusion. I’ll let you know as soon as I hear more.

Thanks for letting me know about the problem. I hope it is sorted out quickly.

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about wikis, Confluence, technical communication, technical writers, and of course chocolate.

Follow Ganache, technical communicator extraordinaire, inside Confluence wiki for an in-depth guide to developing and publishing technical documentation on a wiki. Then, with the groundwork done, you will see how to make your wiki fly.

Experience life as a wiki author and reader. Working in an agile environment? Wikis were made for that! Wondering about search engine optimization (SEO)? Wikis can do that too. Learn how to harness the wiki’s social and collaborative features, turning technical documentation into true communication.

The book is also the confluence of technical communication and chocolate. Because you can’t have one without the other!

I hope you enjoy it. 🙂

Details

Pre-order at Barnes & Noble: http://www.barnesandnoble.com/w/confluence-tech-comm-and-chocolate-sarah-maddox/1038398637?ean=9781937434007

More details of the book at XML Press.

A book about technical communication on Confluence wiki

Big news: I’m writing a book! It’s about developing technical documentation on a wiki, and specifically about Confluence. I started the project six months ago. Now the content is written and the technical review is about to start! Exciting and scary, all at once.

This is the title of the book:

Confluence, tech comm, chocolate

A wiki as platform extraordinaire for technical communication

It will be published in early 2012 by Richard Hamilton at XML Press.

What’s in it?

The book is primarily a guide to developing technical documentation on Confluence. But that’s not all. There are ideas and philosophies, tips and tricks, and special notes for technical writers about why a wiki is the tool we dream of. Many of the ideas apply to wikis in general, although the book focuses on Confluence because that’s the one I know best.

It’s a book for technical communicators, from someone who knows and loves them. It’s also for product owners, CEOs, developers and anyone else who is considering a wiki as a platform for technical communication.

The first part of the book introduces wikis and Confluence. Part 2 is an in-depth guide to developing technical documentation on Confluence. It starts with planning and design, moves on to developing content, through workflow all the way to release management. The more esoteric concepts are there too, such as content reuse, structure, style and online help. In part 3 we see what it’s like to work on a wiki. The book finishes with a section crammed with ideas. It’s all about making the most of the unique features that a wiki provides, to turn your documentation into technical communication extraordinaire.

Just in case you’re wondering: This isn’t an Atlassian project. It’s all my own, though of course Atlassian management and my closest colleagues know about it. It will be fun to see what other Atlassians have to say when they see the book. And when they see this post. 😉

By the end of the book you will know everything I’ve learned in the past four years of working on a wiki. Oh, and chocolate plays a part too.

More coming soon

The illustrations are done. I love them! We’re about to start the cover design. I’ll show it to you as soon as it’s ready.

Who’s in the book?

There are even some characters in the book. I’ll introduce you to them soon. Watch this blog. 🙂

Technical writers hold an innovation sprint

At Atlassian, where I work, the pace is fast and furious. Always. It’s fun, invigorating, challenging, and I wouldn’t have it any other way. But there’s just never a breathing space. So when do we find the time to think about innovative techniques or procedures in our technical writing and documentation? The answer to that one is, all the time. If we have an idea, we’re encouraged to blog about it and see what people think. OK, cool, now we have some ideas. How do we find the time to put them into practice? That’s more difficult.

A couple of weeks ago we held an “innovation sprint”. This is a new idea, designed to tackle exactly the problem of finding that time to try out our innovative ideas. It worked and it was a lot of fun. Chocolate was of course inevitable. We wore some funny hats. And we made great progress on our innovation projects. So I thought I’d tell you about it.

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

What’s an innovation sprint?

Well, it’s a new idea. I haven’t heard of anyone else doing it, but if they do then their innovation sprints may have a different format. Here’s how we ran ours.

Planning: To prepare for the innovation sprint, we set a date and decided what each person would be doing during the sprint.

To take a step back, let me tell you about our “innovation register” and “innovation deputy” role. We already have an innovation register where we collect any ideas coming from us or from anyone else. The idea has to be something new. It can be procedural or part of the documentation itself. We also have a designated innovation deputy, a team member who is keen on innovation and who brings in new ideas, coordinates activities and makes sure everyone has an innovation project to tackle. The idea of an innovation deputy is also new, and I’ve filled the role for the last 6 months. The team lead and innovation deputy regularly discuss the new ideas with the rest of the team, and together we all decide which items are feasible and who would like to tackle what. So we made use of this register for our innovation sprint.

The sprint: We allocated a day for the innovation sprint itself. Yes, a whole day. Luxury! On that day, the technical writers planned to do nothing except work on an innovative idea for our documentation. Preferably, the project should be something that’s agreed upon beforehand with the rest of the team, and preferably it should be an item from the innovation register.

Demo: We also allocated an hour a couple of days later, where each of us demonstrated what we had managed to achieve during the sprint.

Hint: Schedule the demo session for a couple of days after the sprint. Even better, put a weekend between. That way, people have time to tidy up what they did and compile their demo. In our case, two of us were so fired up by the sprint, which happened on a Friday, that we worked over the weekend to finalise our project and have something to show. Cheating? Nah! Because it’s all about the ideas and the feeling good, not about the time.

Why the funny hats?

We wanted a tactful way of letting people know that the technical writers were otherwise engaged for a day. It worked. And it was funny. Here’s a typical conversation I had a few times with people coming into the office that day:

Newcomer: Is it tech writer hat day?
Me: No, we’re doing an innovation sprint today. The hats are a subtle way of saying, “Keep off, no doc requests today.”
Newcomer: Oh, that’s your thinking hat!

What did we get done?

A lot!

Giles continued working on his automated documentation publishing tool. This is a long-term project, fondly known as the “releaserator”, aiming to automate some of the procedures the technical writers follow when publishing documentation updates on release day.  We write and publish our documentation on Confluence wiki. There are some things the wiki does not yet do, from the point of view of publishing technical documentation. Giles is developing a plugin for Confluence to fill some of the gaps. The releaserator now has an awesome prototype of the configuration screen it will need in the Confluence space administration section. As a bonus, Giles is now a Velocity fundi. (We’re not sure that he ever wanted that distinction, but hey, who’s complaining.) Here’s the prototype of the configuration screen (click the image to see a larger version):

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Rosie continued with her flowchart visualisation project. The aim is to use Gliffy to display a hyperlinked diagram at the top of each page in a procedural document. The diagram has a box for each stage in the procedure. The step you’re currently working on is highlighted and the boxes are hyperlinked so that you can move easily from one step to another. This project is not yet visible on any published pages. Here’s a screenshot of the prototype:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

Andrew started work on a shiny new conceptual overview of Confluence wiki, also using Gliffy. Although still a work in progress, this page will soon become an awesome and useful document for our customers. It consists of a couple of diagrams showing the conceptual components of Confluence, such as the dashboard, spaces, pages, comments and labels. Each component is hyperlinked to the documentation page that describes that component.

I finalised my project called “Tips via Twitter”. The aim is to encourage people to tweet hints and tips about our products. What’s more, we publish a live Twitter stream on a page in the documentation. Tips via Twitter is now live for one of the Atlassian products, Confluence wiki. After one month’s trial, ending in mid-July, we will decide whether to roll out Twitter tips for another product called JIRA. I wrote about this project in an earlier blog post: Hints and Tips via Twitter.

What about the chocolate?

Ed, our team leader (not pictured above), went on a quest throughout Sydney to find some unique chocolates. Since the Atlassian technical writers are all such chocolate connoisseurs, it’s hard to find something new. But Ed came up trumps with these chocolates from Adriano Zumbo Chocolat Café in Balmain:

Technical writers hold an innovation sprint

Technical writers hold an innovation sprint

The flavours were, well, unique:

  • Strawberry and balsamic (front right, the smooth square one with silver dust on them). Pow! Taste sensation. At first powerfully sour. Then a bit overwhelming, but suddenly melting away to nothing at all. This was my favourite.
  • Chilli (front left, the dark, igloo-shaped one). Nothing special, actually.
  • Lemon (middle right, the corrugated one). Sour. Nice, but not as dramatic as the strawberry ones.
  • Dark chocolate honeycomb (middle left, the irregularly shaped one). Tasty. More or less as you’d expect, and nice and fresh.
  • Coconut, coriander and cardamom (at the back, the coconut cluster). Good. Again, more or less a conventional coconut cluster, but nice and fresh.

The innovation sprint was good. We plan to hold them regularly from now on.

%d bloggers like this: