Generations Change, But Help Formats Remain the Same?

Today should have been a day of great excitement, almost like a coronation. Having struggled with a 175 page user manual for several months, I finally finished a first draft. Today I met with the client, alongside the senior project manager, the project manager, and a few others to present the sacred document, with the words “Reference Manual” on the front.

I say it should have been a day of celebration. Instead, it was an event I knew was out of date. The client flipped through the manual, glancing. He then set it down and we talked about reviewing schedules, because no one felt the client would actually read the manual on his own. Yes, we had to nail down a schedule and force him to choke it down in weekly bites.

In truth, I dislike delivering “the manual.”

In “Move over DITA – Chaos Is Coming!,” Alan Porter suggests that rigid structural writing, such as DITA, is at odds with the looser, more chaotic social media so prevalent among the younger generation. Rather than trying to force-fit the DITA standard onto our documentation, he says we might instead “step back and look at how [our] kids do their homework. Because in five to ten years they will be [our] new workforce, and perhaps more importantly, [our] new customers.”

In other words, we should rethink our documentation model. Rather than a rigid structure, we might consider following the pattern of how people actually access and use information today.

Exactly how do kids do homework these days? Alan says his daughter uses a variety of social media applications — wikis, social networks, instant messenger, folksonomies, social bookmarking. Observing his daughter complete her homework, he writes,

The first thing she did was google “Pearl Harbor” and started visiting links. First stop was Wikipedia. Then she got on Facebook and YahooIM and started using messaging to ask friends who were online for recommendations. These friends were literally from all around the world, so she was given access to resources that gave totally different perspectives than those given in the classroom. …One friend suggested going to a social bookmarking site and searching using a variety of user applied tags. Instead of taxonomy she was now applying folksonomy.

In a recent IT Author podcast, Alistair Christie interviews his daughter about how she uses computers, and his daughter explains that she never uses the help, because it’s almost impossible to find what you’re looking for. Instead she learns by simply using the interface, clicking buttons, looking at labels, and asking others for help if she needs it. The world of traditional help deliverables — long manuals with table of contents and indexes, expandable books in online help, even video tutorials — these all seem last resorts in user’s mind.

I don’t use the DITA model, but I do use standard topic-based authoring methodology, single-sourcing between online help and a printed PDF. Reading Alan’s post and listening to Alistair’s podcast, as well as hearing the feedback I always hear about help –- “I try to learn the application on my own first, and only turn to the help when I’m stuck” –- makes me think the old-school paradigms of help (the manual and the online help) are falling by the wayside. They aren’t harnessing the latest social media technologies. They aren’t appealing formats.

Alan also observes a sad truth:

For most of my working life to date, the technology I used at work far outpaced that I used outside of work.

But not any more.

Now the technology I use at home has generally outpaced that found in most workplaces.

This is the tragedy of technical communication. Rather than embracing and leveraging the latest web technologies, tech comm is stuck in the early 1990’s, delivering the same old content that no one wants and few can make sense of.

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.

  • Eddie VanArsdall

    This post really resonates with me. I’m still using traditional tech comm models in my work, but I’m trying to convince clients to do otherwise.

    I must, however, give credit to the National Cancer Institute (NCI) for stepping outside of the box just a bit. Although we create FrameMaker books and traditional online help, we are increasingly using wikis to disseminate and manage information.

    For the MediaWiki project at, I add help topics directly to the production wiki. The results are immediately available, and the reviewers can edit and update as they wish. I enjoy this project because it’s about the writing and the content–not the tools.

    We also collaborate on project information using a Confluence wiki.

  • Mark Rudden

    So, perhaps the best place for help is embedded in the application, where users look first anyway. Zero-click help is certainly appealing to me as a user.

  • Craig

    I might have part of the answer. Back in the 1990s, when the web was new and the boom was just beginning, software was free and updates were infrequent.

    Now software costs money and takes time to learn. Updates are frequent. People think they have enough to learn with Office 2007. They don’t want more.

    This month’s cool new software might be replaced by super-cool new software next month. At home you can keep up easily . Not so much in the office. Which software do you buy? Whose recomendation do you take?

    Then once you want something, do you have to get everyone, like the board of directors or vendors, on the same page?

    Most of the time, it really is easier sticking to things that still function. Doesn’t matter if no one outside uses them.

    The old adage applies here. It it ain’t broke, don’t fix it.

  • Collin Turner

    I agree with this. Completely.
    Even the “High-Tech” companies I’ve done work for still cling to old methods that seem to force users from the documentation.

    Often I wish someone would tell me “Put it together in a way you think will work, we trust your opinion.”


  • John Hewittq

    My struggles to convince my company that wiki is the way to go have been painful and fruitless. I keep trying to make web help do things it was never designed to do, fully knowing that the customers are dissatisfied with the delivery.

  • Sue

    My primary client is utilizing wiki based help. It’s very popular with even the help-averse engineers.

    I’m working on single source help for an application as we speak, and in addition to embedded help, the client wants a printed manual. I doubt anyone will look at it. Ever.

  • Pingback: 12/10/2008 Writing Jobs and Links | PoeWar()

  • Joe

    “I’m working on single source help for an application as we speak, and in addition to embedded help, the client wants a printed manual. I doubt anyone will look at it. Ever.”

    I remember going on a site visit two years ago and observing something similar. The product I was working on at the time was so large and complex, there were literally 12 different manuals that went with the application.

    While answering a question about error messages, one of the users remarked “I wish there was someplace we could find out what the error messages mean.” I promptly asked her for a copy of the System Administrator manual, which she had no idea that they even had. After an extensive search, we found the manuals, still in a box, in a store room. I showed her where the section was that documented each error message along with an explanation, and she was amazed.

    I agree that a lot of places are using out-dated business models for their documentation. My current job is the first place I ever worked that used single-sourcing.

    My only problem with Wikis, etc., is like the Internet, there tends to be too much information, a lot of it useless junk, or obsolete.

    To me it goes back to knowing your users and what they need to know to do their jobs. In my experience, very rarely (if ever) do users read the manuals. And most will only go to the online help as a last resort. I never use Microsoft’s help, preferring instead to just google my question.

  • BG

    I seem to hear “nobody uses the manual” since forever. And it’s always true – and always false. It depends on the target audience. It depends on the software. It depends on the quality of the manual. There will always be people who print out things, or rather test around forever, or give up (worst case).

    I fully agree that the manual is only part of the user assistance. The software needs to be good, the GUI well-done and perfect for the necessary tasks, there should be a forum with quick support, and email addresses for specific questions.

    However, simply writing the user manual is a process that improves the quality of the overall-product because suddenly questions are asked that the developers wouldn’t ask themselves.

    Wikis are fine, but as a tool they don’t solve any problems per se – they still need structure and someone who cares for the overall content, and people who are willing to write and read these contents.

    Fact is, the more complex the jobs the software should do, the more complex the manual because it needs to cover more ground. The idea that learning new tasks is completely painless and done in a second is a nice vision – and for sure, lots of applications out there are far from doing their best in terms of usability – but it’s also an unrealistic idea.

  • Pingback: Freelance For Free » 12/10/2008 Writing Jobs and Links()

  • oldschool

    I hate to be a party pooper on the “new technology” bandwagon, but it’s always been true that user’s don’t want to read the manual / help, and only consult it as a last resort. And I don’t think changing the delivery format for the information is ever going to change this. People want to accomplish their tasks, not read our perfect prose. And that’s true whether the info is in a wiki, on the web, or embedded in a manual.

    Don’t believe the “nobody reads the help/manual” thing. Some people never will. The rest won’t admit that they have. But the “expert” that answers questions (in person, via a forum post, via IM etc.) often has.