Alan Brandon

With the combination of responsive web design, modern content tools such as Madcap Flare, and the proliferation of mobile internet devices for viewing content, it has become so much easier for technical communicators to design and create documentation that meets the need of their audience when — and where — they users need it.

While the leading-edge examples get the buzz in tech comms circles, I think the majority of user docs are still designed according to concepts and practices from five or ten years ago. That is, they still have at their heart a WinHelp or even paper baseline for the design and content decisions.

Many old-school technical communicators have an “architecture mindset” as Ethan Marcotte describes in his post on A List Apart:

English architect Christopher Wren once quipped that his chosen field “aims for Eternity,” … Unlike the web, which often feels like aiming for next week, architecture is a discipline very much defined by its permanence. … Creative decisions quite literally shape a physical space, defining the way in which people move through its confines for decades or even centuries.

For each separate viewing experience — paper, online help, web, mobile — designers would (and often still do) create a new architecture for delivering the content. But now the tools and support to truly separate the content from its delivery are widely available.

Not all technical communicators want to work this way. It’s different, and possibly scary. As Scriptorium’s Sarah O’Keefe keenly notes:

Technical communication is in the midst of a huge transition from a craft/artisan model to an engineering model.

But I think most professional technical communicators welcome the new technology, and the new opportunities to deliver information in better ways. As responsive design, flexible content tools, and mobile delivery truly hit the mainstream, they will bring a huge, positive change to the way user documentation is created and delivered.

You’ve got to love an article that starts:

It’s important to understand what clever technology developers and open source leaders have known for years: Great product documentation isn’t loathsome — it’s marketing, and darn good marketing at that.

Mike Puterbaugh, VP of marketing at MindTouch, has a great read at Mashable titled 5 Reasons Your Product Documentation Is a Marketing Asset. In it he lists five things about quality product documentation that can make it a strategic resource for finding and keeping customers.

Here’s a quick summary, but it’s worth reading the whole piece.

1. Credible Language vs. Marketing Lingo

Should your documentation look or read like marketing copy? Of course not. Documentation is decidedly not marketing copy. It should be credible, and absent the jargon and salesmanship that customers and prospects have come to expect from the marketing kind.

2. Search Engine Optimization

Documentation should be keyword-rich, densely linked and expertly structured. Importantly, it doesn’t raise the red flags that other types of content might.

[ I disagree somewhat with Mike's approach that documentation should be seeded with SEO keywords. Good documentation will already have all the keywords necessary for it to score well in search results. ]

3. Cross-Functionality

First and foremost, documentation responsibilities should probably fall within the CMO’s duties because that’s where its effect starts and stops.

[ I have experienced this firsthand. The doc departments that I have run within Marketing groups have been the most effective in producing good documentation. ]

4. Community Building

Although documentation has a bad rap for being wonky, realize that it can actually present an opportunity for community and customer congregation.

5. Identifying Needs

Documentation is a very effective way of identifying unmet customer needs. It holds a wealth of information that your product team will drool over, and yet that feedback loop is seldom taken advantage of. What are the most commented-upon items, for example? The most viewed? The most cited?

[ Fortunately, modern tools and publishing make it much easier to track this sort of information. ]

Interesting post on Anne Gentle’s blog, Just Write Click, in which a technical communications student from the University of Minnesota asks:

Can Twitter really be used for documentation…?

The answer, of course, is no. Or is it? It depends on how you want to describe “documentation”.

Your customer is not going to look up CLI command using Twitter, but Anne sees some “documentation” use cases that could possibly be met with Twitter:

Sure, people are using Twitter for posting tips and tricks and … for Twitter chats…. Twitter can be used for the goals met with traditional documentation when the goals are customer support or service, engagement, adoption, research and feedback loops, …. So yes, Twitter can be used for documentation, when documentation’s goals align with some Twitter use cases.

I think most of those use cases fall under “customer support”, which is where your customers go when your documentation fails. (And “engagement” seems more like marcomm than tech comms to me.)

Twitter is closer to the telephone or radio than it is to electronic or paper publishing. And as such, it’s more suited to customer service and support, and marketing, than it is to instructional or reference documentation.

When I was starting out in technical writing it was common to define terms such as CPU, MHz, and RAM, whether in-line or in a glossary. As such high technology became more mainstream, it was no longer necessary for most audiences. MHz and RAM seem to be understood by most of the general public. Indeed most non-technical readers can comparison-shop for a new phone or camera using these technical specifications.

But other industries are newer to the mainstream. For example, many of us learned new financial and business terms when our banks were bailed out and our 401Ks evaporated. Suddenly many writers needed to cover new topics, with new terminology that wasn’t familiar to their audiences.

Enter The Financial Writer’s Stylebook by Chris Roush and Bill Cloud. The book features definitions for 1100 terms, plus information  on legal issues specific to financial and business reporting.

Such a style guide should help writers who are new to financial topics — or whose audiences are. As Bill Cloud says on the American Copy Editors Society website, “There are fewer dedicated business copy editors. The confidence level it gives, whether to define something or not — I think that’s important.”

The book will be available in November.

I loved this excellent article by Julia Turner on Slate about hand-drawn maps — the kind of maps you draw so your cousin can find your house, or your buddy can find the boat launch. In these days of Map Quest, Google Maps, and turn-by-turn GPS directions, a hand-drawn map can seem like an anachronism. But when you sketch out a route on a Burger King napkin you’re providing better clarity, customization, and resolution than the latest smart phone app.

The crucial advantage of the handmade map is that it is designed for a particular person confronting a particular task.

Like good technical documentation, a casual hand-drawn map is designed for a specific purpose. It therefore leaves out the unnecessary bits and simplifies the presentation of the key information as much as possible. Take roads for example:

Handmade maps also tend toward straight lines and right angles, a phenomenon spatial psychologists refer to as “rectilinear normalization.” The world is full of squiggly roads that intersect at oblique angles. When we envision space, though, we tend to reduce such complexities to relatively simple geometric forms.

And one more example of how hand-drawn maps are like tech docs:

Another advantage of personal cartography: Homemade maps often include error indicators, signs that you’ve taken a wrong turn or gone too far.

Turner provides a link to the Hand Drawn Map Association website, which is worth checking out as well.

(Slate via Boingboing)
(map: Laura Watson via Slate)