Finding a Conversational Voice in Video Tutorials

A voice over is a voice narration from a performer whom you can’t see, who reads a script in an engaging way according to the context of the script. For example, many commercials employ voice overs from professionals. The difference between voice-over performers and announcers, Scott says, is that voice-over performers get outside of themselves, whereas announcers merely read a script.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Video>Podcasting

Does Twitter Fit into Your Branding Strategy?

Twitter, often referred to as the water cooler of the Internet, teaches us the art of brevity by limiting communication to 140 characters or less. But unless you can compress instructional content in ingenious ways, you’ll find Twitter limiting as a method for delivering documentation. Instead, Twitter is better used for the following: eavesdropping on customer conversations; putting a personal face on your company; and increasing the reach of your announcements.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Web Design>Marketing>Blogging

EServer TC Library: The Most Popular Technical Communication Website in the World

The EServer TC Library dwarfs all other tech comm sites. Granted, EServer TC Library is a library, which people primarily use to browse content located elsewhere, so it’s perhaps not in the same category as the other sites. Still, the sheer amount of traffic is impressive. I caught up with Geoffrey Sauer, the creator of the EServer TC Library, and chatted with him over email.

Sauer, Geoffrey and Tom H. Johnson. I'd Rather Be Writing (2008). Articles>Interviews>TC>Body of Knowledge

Documentation Honesty and Poor User Interfaces — An Ethical Dilemma?

We’ve all run in to situations where we have to document poor user interfaces. As much as we complain and suggest improvements, the project manager decides to go ahead with the interface as is because redesigning it is too costly. When I run into these situations, rather than insult the interface in straightforward talk in the documentation, I euphemize the language (against my better desires) in order to maintain the consistency of the company voice. It just doesn’t sound right to be so frank.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Ethics

When Trust Becomes a Characteristic Flaw in a Project

As hard as it may seem, lesson one of technical writing is to break the rules and contact the end user. Conduct a mini-ethnography. Sit with the users. Call them on the phone. Send them emails. Do not let it get to the point where you feel you must go through the PM to communicate with the end user. As hard and uncomfortable as it may be, the consequences of not talking to the end user can be crippling to your help.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Project Management>Collaboration>Technical Writing

Good Designs Have Strong Contrast

Push contrast more than you might be naturally inclined. If you don’t, you end up with conflict. The next time you eat at a restaurant, look closely at the menu. A good menu has a high degree of contrast between sections.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Document Design>Graphic Design

Where I Stand on the Darwin Information Typing Architecture (DITA)

DITA provides the ability to chunk information, to deliver selected topics in a variety of compilations and output to various formats. It allows the passing back and forth of this content among authors regardless of tools. My hesitation with DITA has only been that it’s too early to adopt. But I believe the turning point has come.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Information Design>XML>DITA

A Five-Click Solution to Publishing and Uploading Screen Videos to SharePoint

The quickest video solution for uploading Jing videos to a SharePoint directory. This process requires a few minutes of setup, but once you set it up, it literally takes just five clicks to initiate, capture, and publish a video to SharePoint.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Content Management>Microsoft SharePoint>Screen Captures

Trends in Web Design Involving WordPress

This week I caught up with Debbie Campbell, a Colorado web designer and developer and the owner of Red Kite Creative, and asked her about the latest trends in web design. I’ve been following Debbie on Twitter for a while. This week she posted a few tweets about web design and WordPress, so I asked her to share a little more.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Interviews>Content Management>Web Design

Lessons Learned with Quick Reference Guides: Timing and Truth

I should never fully trust anyone on a project. I don’t mean this disrespectfully, because I work with competent, talented professionals. But no one has the full picture of how the application will truly work. The quality assurance (QA) engineer usually has the clearest picture. The program manager and project manager are often living in a slightly different world, full of a vision of how the product should work and how they expect users to interact with it, but sometimes they’re missing important nuances in the actual implementation. The interaction designer builds prototypes and assumes the developers will build them to spec, but since the prototypes are usually HTML-based, and not in Java or .NET, variances are inevitable.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>User Centered Design>Emotions

Emotional States of Computer Users in Times of Frustration

If there’s one undeniable characteristic of the frustrated computer user, it’s that her patience is gone. She will not be slowly flipping through the user manual. Notice her jerky movements. If she turns to the help (which she doesn’t here), she’ll search for keywords, skim rapidly, click quickly from topic to topic. As we write for users in this state of mind, we have to remember the hurry.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Emotions

Quick Reference Guides: Short and Sweet Documentation

In this article, my colleague and I provide strategies, tips, and approaches we’ve learned in creating quick reference guides for software documentation projects.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing>Quick Reference

Blogging: A New Role for Technical Communicators

The online transition to web 2.0, with its proliferation of blogs, wikis, podcasts, tweets, and other user-generated content, has posed a question for the state of help content. Should help material concern itself with web 2.0? Do users want to interact and contribute to help content in the same way they contribute and interact with web content? What is the technical writer’s role in relation to new media?

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>TC>Writing>Blogging

How Video Can Turn Your Career Around

When I talk to most technical writers, video is a format they haven’t done much with. This surprises me, because I find that, as a user, video tutorials are often the most helpful type of material for me to learn software. Video most closely simulates the universal desire we have for a friend to show us how to do something in an application. Perhaps I’m a visual learner, but the majority of us (some say 60 to 65 percent) are visual learners. But video doesn’t appeal only to end users. Video can be an appealing format for technical writers as well. Creating videos can turn your career around, especially if you find technical writing a little dull.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Multimedia>Video

Ginny Redish — Letting Go of the Words

Anticipate the reader’s questions and then construct your writing as a response. This type of writing focuses you on your audience and gets you thinking about the specific questions, concerns, issues, and other problems your users might have. Each sentence you write should somehow answers those questions — you construct the conversation.

Redish, Janice C. 'Ginny' and Tom H. Johnson. I'd Rather Be Writing (2009). Articles>Interviews>Writing>Podcasts

Two Stories About How to Write Help

The mindset in which most technical communicators write help is sometimes fundamentally flawed. Consider the following two stories and the different approaches and mindsets each writer takes toward the project.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Technical Writing>Help

User Paradox with Not Reading User Manuals

Users would save time by reading the manual, but instead they try to figure the application out themselves and then get lost/frustrated as they end up spending even more time getting up to speed with the application.

Johnson, Tom H. I'd Rather Be Writing (2007). Articles>Documentation>User Centered Design>Technical Writing

STC Toronto’s New Five-and-Five Chapter Model

A podcast interview with Anna Parker Richards, incoming president of the STC Toronto chapter, about their event-driven chapter model, in which they replace regular meetings with periodic all-day events.

Johnson, Tom H. and Anna Parker Richards. I'd Rather Be Writing (2009). Articles>Collaboration>Community Building>Podcasts

The Myth of Simplicity and Complexity in Help Authoring

Although simplicity is a noble ideal, and something like “simplify complexity” could be the mission statement of any technical writer, simplicity is in fact a complex undertaking. The interplay between simplicity and complexity is what technical writing is all about.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Help>Minimalism

How to Avoid Extinction as a Technical Communicator

Although there will always be a need for people to explain technical material non-technical people, Ellis Pratt said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way rather than merely creating it.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Multimedia>User Centered Design

Fictitious Documentation

When it comes to truth, my approach is to be candid and honest in formats that live on the web, which I can update on the fly. But when I’m printing hundreds of copies of a guide, which I know will be pinned up on walls, filed in desk drawers, and laminated for long-term reference, I often lie and don’t mention the bugs, hoping that developers will soon fix them and convert my fiction into truth.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Professionalism>Ethics

Lifelines to the STC

In case you haven’t heard, the STC’s finances are facing crisis proportions. Unless membership stabilizes, it could go out of business in a couple of years. Here are a few recommendations to help solve the problems of the STC.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>TC>Community Building>STC

Documentation Usability: A Few Things I’ve Learned from Watching Users

Even though your customers may not read manuals, your tech support team probably does, which means someone is reading the manuals and using them to help others. But if your users find it easier to call someone, wait on hold for an agent, and then ask the agent a question rather than find the answer in the help, maybe your help materials aren’t very usable. Maybe increasing the usability of your company’s documentation could alleviate the need users feel to seek answers from another source.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Usability>User Centered Design

Changing the Rules of the Game for the Benefit of the User

In this presentation, Joe Sokohl talks about gathering user research prior to designing and implementing your help deliverables.

Sokohl, Joe. I'd Rather Be Writing (2008). Articles>Documentation>Audience Analysis>User Centered Design

Starting Points with Quick Reference Guides: Gathering Before Designing

Dan Roam explains that drawing pictures can help you solve problems. He says the first rule is to “collect everything possible up front.” After collecting all your information, you then “lay it all out where you can look at it.” By laying out all the information, you can grasp the whole of it, make connections between various parts, see the important sections, and recognize patterns.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Information Design>Planning