The first edition of our podcast, Communications from DMN, is now available. This edition introduces our podcast and what you can expect to hear in the coming weeks. In future podcasts, we’ll be presenting tips, information, and reviews of software, books, and Web sites that we find interesting and useful, and hope you will too. Tune in. You might just learn something.
The job of a technical writer is to make the complex easy to understand. Far too often, though, this doesn’t happen. Take the subject of this blog entry at Signal vs. Noise.
The entry discusses the description of a conference called “Simplicity: The Art of Complexity.” The description is far from simple. In fact, it’s complex almost to the point of incoherence. Take this excerpt for example:
Simplicity begins, of course, with usability. The wish for user-friendly devices and programs is fervent and widespread.We will realize how justified it is when we inspect the plethora of shabbily designed user interfaces that hit the retail shelves in ever-shorter marketing cycles. So even as the writers of advertising- copy are busy ballyhooing the latest results of their company’s purported fixation on user experience and user-centered design, the reality that we, the ones who have actually purchased these applications, are familiar with is, sadly, a different one. How very often we wish that industrial designers would pay more frequent courtesy calls on media artists and soak up a bit of the ambient inspiration during their visits!
Either the entire description was badly translated, or it was written by someone whose native language isn’t English. If it was written by a native speaker, then that person should be sacked. Or, at the very least, sent to a remedial writing course.
Ranking third behind the United Nations and the military in its use of acronyms is the tech world. Look online or in a piece of documentation and you’ll find things like SNMP, TCP/IP, MMS, CPU, POP, and more. Some acronyms are common, others less so.
The challenge is how to deal them in user and technical documentation. Many technical writers use the old journalism technique of introducing a a concept early on, then using the acronym throughout the rest of the document. This technique is fine in an article, which is short compared to a manual — readers have an easier time remembering what the acronym means.
But documentation isn’t like an article. People generally don’t read a manual from beginning to end. They use manuals as a reference, jumping to different sections as needed and not following a conventional narrative flow.
So, how should you deal with acronyms in that case? I like to re-introduce an acronym whenever it’s used in a chapter or section. It keeps the concept fresh in the reader’s mind. In HTML documentation, you can easily code the document so that the meaning of the acronym is displayed when the reader holds the mouse over it.
And always try to include a glossary. You can make it as long and detailed (or not) as you wish.
An essential part of a software technical writer’s toolkit is a screen capture program. This article is an excellent review of some of the most popular screen capture tools available for Windows. The focus is on commercial screen capture software. There are, however, a handful of good free applications too. One of our current favourites is FastStone Capture.
We have to disagree with the author referring to a screen capture tool’s lack of image editing capabilities as being a weakness. For us, screen capture software does a specific job. It doesn’t need to be anything else. If we need to edit an image, we’ll pull it into a program that’s designed for image editing.
Technical writers often walk a tightrope. Our job is to make the complex simple, or at the very least simpler. Many times, though, technical writers (either inadvertently or not) make things too simple. This, in turn, does their audience a disservice.
Here is an interesting article on the difference between dumbing something down and making it easy to understand. It was written with Web developers in mind, but the article is also a good read for technical writers.
Yes, we’ve decided to take the leap and produce a weekly podcast aimed at technical communicators and the people who employ them. The first edition of the podcast will be available on December 4, 2006.
Watch this space in the coming days for more information.