Content strategy, Tech Writing, Trends /

The book as podcast

Eric Hellman has a super post about “the book as a container”. In it he defends the book as an excellent way to deliver content for which context is not as important as timelessness.

We need to understand what it is about the book that makes it a container of media that will persist into the digital world. It’s NOT context. The wonderful thing about the book as container is the same thing that lifts Radiolab as podcast above Radiolab as radio. It’s the timelessness. …So as we evolve the ebook, I think we need to be aware of and nurture its potential for timelessness. If we put the context first, as O’Leary urges, then all we have left is a website.

The technical communications community is often as guilty as any in rushing to publish everything as pdf/web/wiki/social/flavor-of-the-day. As publishing choices increase, it becomes more important than ever to choose the right media for your content, and not discard any choices just because they are “old”.

Process, Tech Writing, Tools, Trends /

Any doc, any place?

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.

Marcomm, Tech Writing /

Product documentation as a Marketing asset

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. ]

Tech Writing, Writing /

Can Twitter be used for technical documentation? (Hint: No.)

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.

Tech Writing, Tools /

Financial writer’s stylebook

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.