Search results

Generations Change, But Help Formats Remain the Same?

by Tom Johnson on Dec 9, 2008
categories: technical-writing

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.

About Tom Johnson

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.