Perceptions, within and without

A tech writer? Recently, I met with a prospective client to discuss a project and how DMN Communications could contribute to it. To be honest, the information that I received about the technical communication role in this project was somewhat inaccurate.

The role had a wider scope than I was led to believe. Once that was straightened out (early in our discussion, thankfully!), I explain DMN’s approach to documentation. After my explanation cum pitch, the person with whom I was talking seemed pleasantly surprised.

When I asked why, he said that he’d talked with other consultants and they were expecting to get content from SMEs and others, edit it, and format it in a nice template. And that’s definitely not what this company was looking for.

But that brought home yet again a perception that some organizations have about technical writers.

Continue reading

Ranting (again) about error messages

Frustration with bad error messages As you may or may not know, one of my pet peeves in the world of technical communication is error messages. Make that bad error messages. We’ve all seen them. Many of us have fallen victim to them. They’re frustrating, to say the least.

Case in point: over the last month or so, I’ve been selling various things on More to thin out the books, DVDs, and CDs that have been piling up around my house for … well, a long time.

Things were going quite well until about two weeks ago. That’s when I got a return request. The return request wasn’t the problem. But to process the request, I have to jump through a few of Amazon’s hoops. The first step is to approve the return request. Sounds simple, doesn’t it?

Continue reading

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

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