Embracing the New Vernacular Instead of Pursuing the Holy Grail of Single Sourcing
For a long time, I looked at help authoring tools in terms of their single sourcing ability -- creating the source material in the tool, and then outputting to online help, print, and other targets. However, I've given up on the ideal, at least for now. I'm convinced that the new vernacular, as a SXSW podcast called it, is audio and video.
If faced with a decision between learning via written instructions or audiovisual screen demos, which would you prefer? In most situations, I prefer the audiovisual. When learning software, most users want someone to show them how, to sit beside them and walk me through the steps in a lively, dynamic way.
If audiovisual is the new vernacular (look at the proliferation of online videos, podcasts, gaming, webinars, etc.), why are we wasting so much time trying to single source between online help and printed manuals, confining ourselves to the written medium? Instead, the following deliverables might yield better user results:
- A 1-2 page Quick Start Guide that gets the user up and running with the core tasks in the application.
- 5-10 short screen demos that show the user how to perform the tasks.
- A comprehensive online help that the user can search to find further information in the instant he or she needs it.
For too long I've minimized the importance of the audiovisual. Captivate -- the industry standard tool for creating screen demos -- is actually a relatively simple application. Mastering it and integrating audiovisual into user help will take it to the next level.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
Your post makes one think! Great article. Thanks for allowing me to comment!
I really liked this post... got me thinking. My company has been producing paper reference manuals for a long time now... and people do love them. They love the power of EVERY ANSWER being at hand. And since most of our users are over 50, they love the paper. And our raw, single-sourcing solution means we can produce a Web version at the same time we produce a paper version.
But moving forward... a quickstart guide, a series of how-to-videos, and a comprehensive, searchable built-in (or online) help might be the key to good software documentation.
I'm thinking that a "manual" is no longer the center or "heart" of the documentation. The help engine is. And producing manuals off of that, for specific purposes, is fine... but not the center. Interesting...
I should clarify my post more. I mostly meant that instead of trying to reproduce an online help with a long paper manual that essentially offers the same material but in printed form, we should focus our efforts on providing more audiovisual content into our online help. Reason being, people seem to prefer this medium for learning.
I'm not advocating abandoning online help at all. Like Gordon said, often you want to search for how to do a task, and you don't want to sit through a video. Agreed. In fact, the lack of search for videos is problematic.
Also, I should admit that my definition of single sourcing here is narrow. Of course there is single sourcing with online help to multiple targets for different audiences, and publishing to different formats. I'm not advocating against that.
In an ideal world, we could offer the same content in online help, PDF, mobile device, video, and braille. But usually time constraints limit what we can provide. If so, we should focus on the online help and audiovideo formats first (of course it depends on your audience ...).
I've never seen anyone get excited at "long" manuals I produce for them. By long I mean anything over 30 pages. In fact, I remember giving someone a 27 page guide and seeing his totally disappointed reaction. He wanted a much shorter guide because it suggests that the product is easy to use. Users want 1-2 page guides to get up and running. Then when they need help, they search for a particular task using online help. At least that has been my experience.
The audiovisual medium is important when the task is tricky to describe, or if seeing the process makes it more understandable.
Funnily enough this is echoed by Adobe. I saw a presentation by them on Wednesday this week and they oooo-ed and aaahhh-ed over the ability to add video to a document.
So why don't we concentrate on that? Possibly because we know that (relatively) no-one reads documentation, they only turn to it for help.
If I'm stuck with a product, the last thing I want to do is sit through a 2 min video, I want an answer and I want it now!
Yes they are useful if you have the time to use them, but I guess it's seen as a luxury? I'll expand on this on my blog I think...