Documentation is important, but so is good writing  Clip to Evernote

The article “Putting the Writer Back into Technical Writing” is an interesting treatise on the role of technical writing, and on how good writers can improve documentation. Often, I find that the role of good writing is undervalued in technical writing.

However, being a good writer doesn’t mean that you’ll be an effective technical writer. You really need to balance the skills of a writer/researcher/editor with the technical knowledge required to do the job.

Quadralay’s WebWorks wiki  Clip to Evernote

One of the more popular tools for generating online help is Quadralay’s WebWorks ePublisher Pro. The product is solid, but it has a fairly steep learning curve. But now there’s something to help both the fledgling and experienced ePublisher Pro user: the WebWorks wiki.

Even though the wiki has only been around for about a week (as of this writing), it boasts an extensive FAQ section and growing reference portion. On top of that, there are screen demos of the product. The tips are a bit thin at the moment, though.

Like any other wiki, users can add and edit pages (registration required). So, if you have any tips, WebWorks tricks, techniques or templates you can share them with other users.

Our podcast debuts  Clip to Evernote

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 podcast is hosted at Podbean.com and you can play it directly from our site there. Or, you can download the podcast and listen to it when you wish.

You can read a transcript of the podcast here.

We hope you enjoy our podcast. If you have any questions or suggestions please feel free to leave a comment with this post.

Making the simple complex  Clip to Evernote

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.

Acronyms, acronyms  Clip to Evernote

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.

On screen capture software  Clip to Evernote

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.