Embracing the New Vernacular Instead of Pursuing the Holy Grail of Single Sourcing

Help should be like having a friend sitting beside youFor 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.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • http://www.onemanwrites.co.uk/ Gordon

    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…

  • Pingback:   Documentation: words versus video by Communications from DMN()

  • http://idratherbewriting.com Tom

    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.

  • Pingback: one man writes » This is not a video()

  • http://learn.pcc.com/ Douglas K. Beagley

    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…

  • http://classes.pi.edu/ Education Blog

    Your post makes one think! Great article. Thanks for allowing me to comment!