#33894
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
#33909
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
#34252
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
#34253
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
#34254
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
#34371
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
#34378
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
#34382
Quick Reference Guides: Short and Sweet Technical Documentation 
Users often want documentation in a format that will give them the basics and get them on their way as fast as possible. Quick reference guides provide a short version of a manual, condensed from dozens or hundreds of pages down to just one double-sided sheet of paper. Despite the brevity of quick reference material, the thought process involved in creating, organizing, and laying out the content is time consuming. The format requires you to assess the content and decide the most important information the user needs to know. You must describe with extreme concision and clarity processes that usually require dozens of pages to explain. This article provides an overview of the strategies, tips, challenges, and benefits we have learned in using quick reference guides for our documentation projects.
Johnson, Tom H. and Benjamin Minson. Gryphon Mountain (2009). Articles>Documentation>Technical Writing>Quick Reference
#34401
The State of Structured Authoring in Technical Communication
In this podcast, Sarah O’Keefe of Scriptorium Publishing explains the results of their recent survey about the state of structured authoring in technical communication. In the survey, they found that 84% of respondents are either thinking of moving to structured authoring, are in the process of moving to structured authoring, have already adopted structured authoring, or are undecided. Only 16% of respondents said they were not moving to structured authoring. She also discusses other survey results, such as the adoption of DITA and mistakes people make in moving to structured authoring.
Johnson, Tom H. and Sarah S. O'Keefe. Tech Writer Voices (2009). Articles>Interviews>Document Design>Podcasts
#34402
In this podcast, Mike Hamilton of Madcap Software talks about their phased approach to handling DITA with Flare. In Phase I, you’ll have the ability to import DITA topics and export to webhelp and other targets. In this sense, Flare functions as a transform engine. In Phase 2, you can use Flare for native DITA authoring. Phase 1 is on the cusp of release, but Phase II won’t be available until quarter one of next year.
Johnson, Tom H. and Mike Hamilton. Tech Writer Voices (2009). Articles>Interviews>DITA>Madcap Flare
#34430
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
#34570
Blogging, Podcasting, and Screencasting: Eight Characteristics to Attract Devoted Followers (Part I)
Devoted followers stay updated with each new post, podcast, or screencast, eagerly awaiting the next new one. They’re intimately familiar with your content and either comment regularly or regularly return to your site.
Johnson, Tom H. Tech Writer Voices (2009). Articles>Blogging>Podcasting>Screencasting
#34571
Devoted followers stay updated with each new post, podcast, or screencast, eagerly awaiting the next new one. They’re intimately familiar with your content and either comment regularly or regularly return to your site.
Johnson, Tom H. Tech Writer Voices (2009). Articles>Publishing>Blogging>Podcasting
#34577
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
#34587
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
#34624
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
#34625
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
#34637
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
#34639
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>Technical Writing>Quick Reference
#34669
Review: Page Layout and Design Tips from Jean-luc Doumont’s Trees, Maps, and Theorems
Given the engineering audience, one can’t hope for too much style and flair in the prose, but it reads like a college textbook, outlining basic principles in a flat way. It is too focused on “clarity, accuracy, correctness, etc.” (p.79) to make for a fun or engaging read.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Reviews>Document Design>Visual Rhetoric
#34681
Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services. To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Multimedia>Case Studies
#34711
Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It’s not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>User Centered Design
#34712
A Mile Wide and 30 Seconds Deep: A Metaphor for Help from Mike Hughes
Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Technical Writing
#34726
Why is it that, given the opportunity and tools to write, so few embrace it? I have several thoughts as to why.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Writing>Publishing
#34750
Is This Meeting Really Necessary?
In a world of virtual tools—blogs, wikis, feeds, forums, listservs, e-mail, IM, chat, Twitter, social networks—one would think that the traditional sit-down, face-to-face meetings had been relegated to a place in a historical museum among other old, discarded traditions (like wearing cravats). But even in the 21st century, many people still believe that if you want to accomplish serious planning and discussion, you need an in-person meeting.
Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Project Management>Collaboration
