Weekly links roundup

  • Interested in learning how to document an API? This book will give you a good introduction.
  • This article (it’s a PDF) discusses screencasting, and how to apply it to documentation.
  • One session at the recent CMS/DITA conference examined how wikis “could be an easy entry into the world of CMSs, collaborative authoring, and XML -based outputs”. This blog post at Palimpsest is a detailed recap of that session.
  • Writing useful error messages can be tough. Here are a few useful tips.
  • Sarah Maddox discusses how using a wiki helped her team create some documentation on a very tight deadline.

Thinking like a user

Charles Cooper at The Rockley Blog has written an interesting post on the need to think lke a user when developing a document.

Cooper makes one cogent point:

The fact is, most people, especially those who are new to our product (or concept, or service) just don’t have the background they need to ‘instinctively’ find what they’re looking for. So much of what we think of as ‘instinctive’ is really backstopped by prior knowledge.

Continue reading

Dealing with errors and omissions

Regardless of what we’d like to believe, technical communicators aren’t perfect. Neither are the development and project management teams with whom we work. Sometimes we get things wrong and that makes it into the final release of the documentation. Or, for whatever reason, something gets missed.

Nowadays, most documentation is distributed electronically — as a PDF, HTML, a help system, or all of the above. So, it’s a lot easier and cheaper to issue updates to documentation. In a number of shops in which I’ve worked over the last few years, updates and changes and corrections have been slipped in rather stealthily: replace the old electronic version with the new.

The other day, I was browsing the documentation at the Web site of Red Hat. I noticed something interesting while I was there: a link to documentation errata. I haven’t seen something like that for a while, and it’s a nice touch.

The errata page links to updates for various guides. There are also detailed instructions on how to submit corrections using Red Hat’s Bugzilla tracking tool.

How do you deal with errata? Feel free to leave a comment.

A different perspective on single sourcing

This blog post asks whether or not single sourcing is the best option for creating documents. I’m not sure that I fully agree with everything in the post, but something that the author wrote struck a chord:

I know a single source of content will save me a lot of work. But for other people in the company it won’t. It will mean more work for them, not to mention a very steep learning curve, an investment in software and a strong training commitment. It will save me lots of time and effort—in the long run—but it’s going to double the work effort of ten other people. Where is the benefit?

Thoughts? Feel free to leave a comment.

Usability: as important as the product

A few posts back, Aaron discussed how “effective usage as a far more important factor for realizing value in a software deployment than features and functionality”. That’s not only the case with software, but with Web services, too.

This short article points out:

Online retailers can win customers by maximising usability rather than lowering prices

The benefits of well-planned usability are obvious. Users are able to get more done quickly and easily with a clean, easy to follow interface. It’s not only on the Web, either. It applies to the desktop, too.

If you want a view of this from the perspective of a technical communicator, then read this post by Gordon McLean. It goes into some detail about the usability process he follows.