A few thoughts about GSoC Doc Camp 2013

(Note: This post was originally published on October 24, 2013 here)

Ever wonder what happens when 20 Open Source enthusiasts from around the world get together for five days? One of the things that can happen is that they write a manual. In fact, three manuals. Which is what happened that this year’s Google Summer (GSoC) of Code Doc Camp held at Google’s HQ in Mountain View, California.

Organized by Google’s Open Source Programs Office and facilitated by Adam Hyde of FLOSS Manuals and Alan Gunn of Aspiration, the event brought together contributors to the following projects:

  • Mallard, a markup language used to deliver online help
  • OpenMRS, an electronic medical record system platform
  • BRL-CAD, a powerful design and modeling tool

Also attending were four folks (one of them being me) — referred to as free agents — who were unaffiliated with any project. Each of us was, however, keen to pitch in and contribute in whatever way we could.

Continue reading

Anatomy of an update

FLOSS Manuals Last week, I ran a one-day FLOSS Manuals book sprint to update the Thunderbird manual that I helped write last year. The usual book sprint lasts anywhere from two to five days — so why did was this one only a single day?

A few reasons. While there were a number of changes to Thunderbird since the team originally wrote the manual, not all of those changes were major. Plus, at the moment, I’m extremely busy. There’s a lot going on in my personal and professional lives right now, aside from the 1,001 things that make them both a joy and a purgatory. One day was all I could spare.

The one-day sprint was interesting. And fun. Here’s a quick look at what went down.

Continue reading

Adventures in modern publishing

letterpress type blocks With apologies to The Buggles

Last week, I gave a talk at FSOSS 2011 about creating ebooks using Open Source tools. If you’re interested, you can take a peek at the slides and notes for that presentation.

This talk wasn’t all theoretical. While I’m definitely not an expert on creating and publishing ebooks, I do have some knowledge of the subject — I’ve been researching this topic for quite some time, and I’ve been working with various Open Source tools. On top of that, I have some practical experience.

As you may or may not know, I published my first ebook recently. And, yes, it is available in the Amazon Kindle Store.

Writing this book was an interesting exercise for a number of reason. Mainly, what was interesting (at least to me) was the approach I took to writing and publishing it. There were a few fits and starts, but I think for this type of book I came upon a solution that works for me.

Why not join me for a peek at how I wrote and published my first, and definitely not last, ebook.

Continue reading

Creating UA with an artistic eye

By Roger Sharp

Pictures at an exhibition I was at a friend’s house the other day and pointed to something stuck to his refrigerator. It was an invitation to a mutual friend’s birthday party from months ago. The card had a photo of the birthday man sitting in a deck chair sipping a martini. The deck had been made cozy by potted grasses and palms that seemed to surround him. The image was printed in sepia tone.

“I just couldn’t throw it out. It looked too good,” was his excuse for still having it.

And so it is with most people — we appreciate beauty. But more than appreciate it, we look at it longer and remember it better. This principle is also true of user assistance.

Continue reading

Internalization and documentation

Practice, practice, repeat I view documentation as serving three main purposes:

  1. Helping users become familiar, and comfortable, with the hardware or software that we’re writing about.
  2. Teaching users advanced tips and tricks.
  3. As a reference for things that users may have forgotten or rarely use.

A big part of the second point is internalization. Making tasks seem like second nature to the user. This was brought home to be recently while doing some audio editing and clean up for my wife.

It’s been some time since I’ve done any audio editing, and quite a bit of time since I’ve done it regularly. That was back when Aaron and I were frequently putting out our podcast.

Continue reading

Taking documentation mobile: apps vs. common formats

A tablet There’s definitely a lot of talk about the mobile universe in our profession. More and more technical communicators are coming to realize that the devices that we carry in our hands and in our bags are becoming a platform on which to deliver information and documentation.

The question, though, is how best to do that?

Recently, I had a rambling conversation with a friend of mine. He’s not a technical writer (or a writer of any stripe), but portions of our conversations often turn to technical communication. I enjoy the occasional talks I have with people outside of our profession. It gives me a fresh perspective on what I do, and for whom I’m doing it.

Our discussion turned to how best to deliver documentation on a mobile device. Now understand that my friend is a mobile junkie. He lives his personal and professional lives on his phone and portable media player. In fact, it’s been a while since I’ve seen him touch a computer.

Anyway, he said that documentation might best be delivered using an app. I thought about that for a few seconds, then had to politely disagree.

Continue reading