User Manual

One of the most common myths about technical documentation is that nobody reads it. Let’s talk about this myth and four big reasons why you shouldn’t believe it.

Most of us can’t honestly say that we learned how to use a television or computer by studying a reference manual. And the Internet — that didn’t come with a user manual, either. So it’s worth asking: who actually reads user manuals?

First, let’s suppose that computer software or hardware ideally ought to be so well designed that users do not need to consult the online help or printed manuals.

This is not an argument for laying off technical writers, but for involving them earlier in the design process whenever possible as advocates for an excellent user experience. Too often technical writers are only hired after software design is done, so that they have less of an opportunity to improve the products.

It is also worth pointing out that reality falls well short of this ideal, especially when dealing with new and innovative products. As much as we would wish it, technology products are rarely self-documenting. They may seem that way to their designers and developers, but only because over familiarity produces a sort of spell on them.

Read more

Using modern versions of Adobe FrameMaker for the first time is a tiny bit like stepping into the Matrix. You know—swallowing the red pill—you stay in Wonderland, and Morpheus shows you how deep the rabbit hole goes.

Except instead of showing you a dystopian reality, Morpheus reveals the world of eXtensible Markup Language (XML)-based technical document authoring tools. After taking the red pill, the mirage of format-based document authoring disappears forever. Yes, you can still return to word processors or old versions of FrameMaker if needed, but now you know there is another option.

Many businesspeople, especially those in charge of approving budgets for technical documentation departments, wonder if technical writers can’t just use Microsoft Word?

Read more

Communication about anything specialized benefits from technical writing, and so does communication involving technology. If you’ve ever used jumper cables, furniture assembly instructions, or test strips for a home hot tub, you’ve encountered technical writing in everyday life.

There are three types of technical writing needs. They are:

  1. Communicating specialized information such as software documentation
  2. Instruction or guidance material
  3. Communication technology itself, including websites and help systems

So you can see why technical writing is everywhere and not limited to fields like finance, law, and manufacturing. Some kinds of technical writing require specialized knowledge. There is also an art aspect to conveying a concept with clarity and simplicity for the right purpose and the particular audience.

Read more

Whenever there are human beings involved, errors are bound to follow. Editing is basically the quality control process for documentation, and so editors are the “QA Engineers for words”. Editors play the role of correcting, condensing, and rearranging content to produce a more correct, consistent, and comprehensive work.

General editing and technical editing are somewhat different. Jonathan Arnett, an Assistant Professor of Technical Communication at Kennesaw State University, says technical editing is “a highly rhetorical, detail-oriented process of ensuring that specialized information appears so that it is appropriate for end users, and technical editors make informed, thoughtful suggestions for improvement toward that purpose.”

Let’s describe the main roles of the technical editor. In this, the first of two blog posts, we’ll look at the stylistic and presentation edits. We’ll talk about copy editing, but you should be aware that larger technical publications teams may separate the duties of technical editing and copy editing into separate roles.

Read more

I’m a big fan of the blog I’d Rather Be Writing. Written by Tom Johnson from San Jose, the blog is an invaluable resource for technical writers as well as an inspiration for blog writers. Not only does the author explore technical writing trends, he also gives away an entire course worth of information on sought-after training topics.

If you haven’t encountered Tom’s blog yet, do yourself a favor and head on over. There’s too much content on the site to cover exhaustively (he has been blogging regularly for over a decade), but here’s a short tour of a few major attractions.

Read more