- 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.
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.
After another unintentionally long hiatus, we’ve posted a new episode of the podcast. In it, we discuss what we’ve been up to and what we plan to do in the coming weeks. Then, we discuss a topic that is very important to Aaron: usability.
You can listen to the podcast here, or use the embedded player below.
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.
How do you deal with errata? Feel free to leave a comment.
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.
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.