Books, documentation, and perception

Two weeks ago, the Google Summer of Code Doc Camp was announced. I won’t go into that event in this post; you can read more about it here. Maybe you’ll get involved, too.

After the announcement hit Twitter, Shaun McCance posted an interesting tweet:

Tweet about books

I know Shaun, and I understand where he’s coming from with that tweet. Thanks to topic-based writing and online delivery, the whole idea of books and manuals seems so twentieth century. And Shaun has been developing Mallard, a topic-oriented markup language intended primarily for the delivery of help. You can read more about Mallard here.

After reading Shaun’s tweet, I got to thinking about the idea of the book.

Continue reading

The cloud and the freelance technical communicator

Working in the cloud A while back, I published a post on my personal blog about cloud computing and writers. While I think that Web-based apps are a useful addition to any writer’s toolkit, I started thinking about how useful they are to freelance technical communicators.

My conclusion? They’re very useful, whether you use them as part of a job or to help run your business.

There are a number of reasons I think that. The main ones are:

  • Ease of access: you can use these tools as long as you have an Internet connection.
  • Simplicity: most Web-based applications are easy to use and follow the 80/20 rule.
  • Filling in gaps: specifically, software that you might not have at a client site. More on this in a moment.

Overall, I find that Web-based applications make me a bit more productive and a bit more flexible. That said, you need to choose the right applications. Here are a few that any freelancer or consultant can benefit from.

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