I was poking around on Slideshare the other day and stumbled across this one pager titled “The ten tenets of effective communication”. (Actually, this is part one of the article, which covers half the tenets) Thanks to Scott Abel for making this available.
The article is focused on marketing and customer communications. But it definitely does relate to technical communication. How? Here are a couple excerpts:
your message, whether written, verbal, or visual, must be audience-centered – focused around the needs of your audience.
Instructions especially benefit from clarity. Who among us hasn’t struggled through frustrating assembly instructions, or the less-than-accurate steps for using software features? And yet it’s this lack of clarity that increases traffic to a company’s technical support lines with the corresponding increase in costs.
Obviously, nothing groundbreaking or earth shattering here but it’s nice to see that some of the struggles we face are common across many forms of communication.
If you use Word to write content (and if you do, I feel your pain), you might want to get yourself a copy Microsoft Word for Publishing Professionals by Jack Lyon. Weighing in at 632 pages, the book is a cookbook-like reference for doing all sorts of things with Word. Like what? Take a peek at the table of contents. Notice that each tip is short — a couple or three pages at the most.
For an unbiased look at the book, check out Keith Soltys’ review. Over the last few weeks, Keith has shared a few of the tips in this book with me and they’re good tips. Really good tips.
That’s what you’re doing when you write documentation, marketing collateral, Web content, articles, or whatever your deliverable is. Freelance writer Bruce Byfield examines this in detail in a post on his blog. Admittedly, Byfield is talking about general non fiction or even fiction writing, but the lessons he imparts in that post can be applied to technical communication as well.
Byfield writes the following about his initial experience as a writing teacher:
When I first stepped in front of a class, I imagined that I fully controlled the experience. As a result, my first semester teaching post-secondary was almost my last. I needed to learn that, while some students wanted to learn, I needed to cajole or entertain others before they would even try to absorb my lesson.
Substitute readers or users for students and you probably understand fully what Byfield is getting at. The people reading your material want to learn — about your company’s products and services, about how to use those products, about how to quickly solve the problems that they encounter.
With documentation, you can collaborate with the user on two levels:
- By giving users what they want in they way they want it. This could, for example, enable users to remix content to suit their own needs.
- Initiating a conversation with users, and incorporting user-generated documentation, comments, and suggestions into your content. This could be tricky as far as copyright and licensing go, but you could do what Splunk does and use a Creative Commons license for all community content.
How do you currently, or plan to, collaborate with your readers? Or is this even in the cards for you? Feel free to leave a comment.
DITA is becoming very serious business. There’s now a DITA Help subcommittee at OASIS. The purpose of the group is four-fold, but their most important goal in my opinion is to:
remove the obstacles to effective use of DITA for Help systems through the creation of best practice guidelines, cookbooks and worked examples, and to promote the use of DITA for creating Help systems and user assistance content
The group has already released several documents. The most intersting one (at least so far) is this one. While I’m not a huge fan of best practices (I’ve found that in multiple cases the best practices aren’t always best), the document does offer some good guidelines for creating online help with DITA. And the group uses DITA to create their documents, to boot.
No, I’m not venturing into the realm of age discrimination with this post. I’m talking about the content that’s made available to customers and vistors to your employer’s Web site. What got me thinking about this was a blog post that I recently read titled “Out of Date Content Should Be Deleted.”
While the post focuses on news stories on a Web site, the same thinking can be applied to documentation and technical collateral. I’ve seen corporate Web sites that contain docs for versions of applications that are several years old. But how much of that information is still relevant, and should it still be made publicly available?
My thought is no. I tend to advise the companies that I’m working with to only make the documentation for the last two releases of a product available on their Web sites. From what I’ve seen, the larger number of customers will be using or have upgraded to one of those versions when the latest edition of an application is released.
Older documentation should be archived, but in an easy-to-find location in case a customer needs it. All you have to do is dig into the archive and send it off.
What are your thoughts on this? Feel free to leave a comment.