Online help. User assistance. That thing that pops up when you press F1. No matter what you call it, user assistance is an important element in the experience of a user. It can mean the difference between a frustrated user and a productive one.

But is today's user assistance all it can be? Are we giving users purposeful information at the right time, in the most effective format, and ultimately in the way that they need it?

We don't think so.

What we're going to discuss in this presentation is a different way of looking at user assistance. Some user assistance practitioners are already doing (in one form or another) what we'll be talking about today. Help authoring tools can, or soon will be able to, generate the kind of purposeful, user-friendly online help that we'll be discussing.

What we're going to say will sound prescriptive. You can take it that way if you want to. Our goal is to open your eyes to a different way of looking at and designing user assistance. Our goal for the next 50 minutes is to have you think differently about online user assistance and embrace a simpler, more powerful way of delivering it.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 1

Think Simple: A Fresh Approach to User Assistance

By: Aaron Davis and Scott Nesbitt

Note: Throughout this presentation, we'll be using the terms help, online help, and user assistance interchangeably.

Yesterday, today, and tomorrow

Envision, for a moment, online help as it was. And as it is. Can you think of any major differences? What do you think about when you hear the words online help?

User assistance hasn't radically changed over the years. Sure, delivery formats have changed, there are some cool single sourcing tools available, and we can re-purpose content for a wide variety of uses. But the structure and design of most help systems and the type of content that they contain, is often the same as it was in 1995. And that's where user assistance has fallen down - by not meeting the needs of today's user.

On top of that, many technical communicators are developing user assistance for more than just the monitor on a desktop PC or a laptop. Consider smartphones and mobile applications. User assistance for a broad range of functionality must be delivered within a limited amount of screen real estate. The online help paradigm as we commonly know it is simply not suitable for these platforms.

Take, for example, Viigo. It's an RSS client for various smartphones. The technical writer at Viigo spent a lot of time

working with standard tools, and yet couldn't get the help to come out just right – it would work well on some of the supported devices, but not others. She eventually turned to XML. Now, there is only one XML document for all supported platforms.

Online user assistance as it was (and often is)

Too often, help is a copy of the user manual in another format – HTML Help, WebHelp, WinHelp, or whatever. Help authors may choose to remove graphics and change cross references to hyperlinks, but users are still essentially getting a version of the manual when they press F1.

Why is it done this way? A variety of reasons. For some, there's a perception that this is the way it's always been done. If it ain't broke, don't fix it. That doesn't mean things can't improve. Inertia from management can also be a problem. There may be time constraints – short development cycles require some technical communicators to hammer out documentation quickly and as best they can based on those constraints. They might have to forego certain niceties in order to get the job done.

Case in point: when we worked at a large enterprise software firm, the PDF output did double duty as the printed manual and the online help for the application. Help was triggered through hooks built into the app that launched Acrobat Reader. Users weren't getting a true online help system that provided purposeful content at just the right time.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 2

Instead, they had to navigate a user manual. There was just too much information for the reader to wade through to get to what they need.

Is single sourcing always the path to take?

Let's talk about single sourcing for a moment. The way many of us do it is first write your content in FrameMaker or Word or whatever. Then, pull those files into a help tool like RoboHelp or WebWorks. From there, output the help. Doing that is familiar. It's comfortable. But in some cases, it's not the best solution.

Sometimes, though, that single sourcing method isn't the best solution. Instead, why not author the user assistance directly? Say you're documenting a simple desktop or mobile application, or one that's served over the Web. In these cases, having a separate printed or PDF manual doesn't make all that much sense.

With the simple application – and by simple, we mean something that's not as monolithic as Word but not as rudimentary as Notepad – chances are users won't look at the manual. OK, that's not so different from normal ... Seriously, though, they're more likely to press F1 to get assistance.

Many Web-based applications are more complex than the simple desktop or mobile application. In this case, the user assistance is delivered over the Web.

With both, it's faster and easier to build purposeful help directly than to first create a guide and then do the usual single sourcing magic.

Here's a good example of this: the help for Viigo, the mobile application that we mentioned earlier. When the technical writer at Viigo started working on the help, she ran into a number of issues:

• Using a standard single sourcing tool, she created tri-paned HTML help. There were too many panes, and the help didn't render well on a mobile device.

• There are multiple screen sizes for mobile devices, and what looks good on one may not look good on another.

• Navigation was a problem, and she couldn't use a nested table of contents.

After a lot of thought and consultation with the company's Web designer, she wrote the help using XML and on-the-fly XSLT tranforms dynamically output the help to all of Viigo's supported platforms.

Another path: think simple

Simple. It's not a four letter word, but it's often treated like one. Simple doesn't mean incomplete, inadequate, or dumbed down. To us, simple means streamlined. When

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 3

creating user assistance, we really need to start with this question:

Are we giving readers the information they want, in the way they want and need it?

That one question is a common thread in our thinking about user assistance. In a lot of cases, the answer to that question is no.

Let's consider the purpose of user assistance. It's supposed to take users from that stage of fumbling in the dark to a level of mastery. Or, at the very least, put them on firmer footing and start them down the road to mastery. The key to user assistance is showing users how to do things, and not telling them what a piece of software or hardware can do.

1.0 + 2.0 = 1.5?

That was the title of a response to a blog post we did on minimalism in documentation. Obviously, the person who wrote the response didn't agree with what we had to say. The main thrust of that person's argument was a) they liked having excess information in the help, and b) a help system without that information isn't complete.

This goes back to what we said earlier: simple doesn't mean incomplete. It means giving users the information that they need, in the way that they need it. If that means removing

any material that disrupts the main flow of the user assistance, so be it. Help should be about what users want to do. The information that users need is often broken up by pages and pages (or topics and topics) of introductory matter and background material. We've found over the years that the people using an application or gadget don't want or need that information. Well, maybe at first they do – it can come in handy when they're getting the lay of the land. But as they progress with using an application or device that supplementary and background information just gets in the way of them learning how to get things done. Think about this: when someone sends you a Word macro, what do you want to do? Install that macro. Run the macro. Make it accessible via a toolbar button. You probably don't care about what a macro is and all the wonderful (or not) things that a macro can do.

Publisher Tim O'Reilly summed it up well when he wrote:

People are looking for advanced tips and tricks. They're not looking for the basics. They're looking for things that will give them more of an edge. And they're looking for it in a style that's fun and engaging.

It's within your grasp to do just that.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 4

Start cutting

A key idea behind thinking simple is getting rid of anything that doesn't advance the goal of the user. And that goal is learning how to get things done in the fastest, most efficient way. In order to do that, you need to cut away anything that the user won't need.

Before getting the scalpel out, do some planning. Take an inventory of all of the content in your user assistance that doesn't explain how to do something. Then, consider:

1. What you can keep in the help

2. How to make that content unobtrusive within the help

3. Where you can move that content if you don't want it in the help

4. How users will access that content from the help

Doing all of that might take a while, but those definitely are worthwhile steps. Then, you can start cutting.

What's up front

So, what's the first thing that should go? You've probably guessed what it is: overview and expository information. Any list of "what's new". That information isn't going to do much to aid the user in gaining proficiency or mastery. But remember that simply because the information isn't the face

of the user, it doesn't mean that it's not there.

Overview and explanatory information can be important. There are ways in which you can separate it from the meat of your user assistance. How? How about:

• Use popups or mouseovers to define terms or give a little extra background information

• Have it appear or disappear with a click – most help authoring tools enable you to do something like this

• Put the information somewhere else – a supplementary help file on the user's network or hard drive, or somewhere on the Web – say, a wiki or a blog. We'll talk more about this soon.

A little deforestation might be in order

If you look at a lot of help, you'll notice that the main navigation is a tree-like table of contents. It follows a familiar linear narrative flow – beginning, middle, and end. But who reads a manual from beginning to end? OK, we all probably know one or two people who do. They're the exception.

We're deep in the age of hypertext. And hypertext makes that kind of linear narrative obsolete. In fact, hypertext probably follows the thought and usage patterns of most users better than the tree-like flow of the standard TOC. Remember that we're not telling a story with documentation. We're showing users how to get things done. And that's what good help does.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 5

Organization

More than anything else, the key to good user assistance is organization. No matter how good your information is, if it isn't organized properly it's going to be difficult to use.

So, what's the optimal method of organization? There isn't just one. The way in which we prefer to do it is to group similar tasks – for example, all of the topics on importing and exporting data. You can structure the base of the hierarchy as a question like How do I ...? Or, you can simply have a heading like Importing and Exporting, followed by a list of topics – for example, How to Export Your Documents.

Nothing revolutionary there. It's being done, but not often enough.

Web 2.0

Remember the days before the Internet was on computers? Or the period in the early to mid 1990s, when it was still something of a novelty: not all companies or individuals were online, or even had computers with modems. In those days, the types of things that we're going to discuss next were pretty much impossible. And not just because of the Internet and Web were new phenomena to many. The tools that were used to create online user assistance were ... well, they were relatively primitive.

But the Web changed the rules quite quickly. And Web 2.0 even more so. The term Web 2.0 is overused, and we utter it with caution. But the concepts of Web 2.0 offer some very interesting options for user assistance. Those options are another key to thinking simple. You can quickly adapt them to your simplified user assistance.

Google or F1?

How do many people get help about these days? Do they press F1? Or do they turn to Google? Often, it's the latter. So, it makes sense to take a few cues from the world of Web 2.0 when building your help.

We find that the following four aspects of Web 2.0 are well suited for user assistance:

• Wikis • Well organized wiki pages can be an effective

online help platform

• They're also a great repository for background and explanatory information

• Blogs • Easy to set up and maintain

• WordPress has a DITA import tool (which we discuss later)

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 6

• RSS • Tagging

Wikis

Let's start off by talking about wikis. We don't have to tell you how deeply wikis have become entrenched in the documentation world. In fact, a lot of firms and many Open Source projects deliver their documentation using wikis alone. Wikis are a great way to publish full user manuals and to get user assistance out to customers. One company that's doing just that is Atlassian.

You might know Atlassian as the developer of the popular Confluence wiki. And Atlassian is one of those companies that eats it own dog food. How? By publishing all of its documentation on a public wiki, powered by Confluence of course. But Atlassian is going one step further with a pair of developer tools called FishEye and Crucible. They've included icons in the user interfaces of those applications. Click an icon, and you're taken to the appropriate documentation page on the Atlassian wiki. And it's not just a single icon in the UI, either. The help is relatively context sensitive, with help icons beside elements on a screen.

With a wiki, you can easily separate overview and background information from procedural and how-to information. Because of that, it's easy to make the help context sensitive linking from an application to a specific wiki page. And there's no reason why you can't structure a wiki

like an online help system. Make pages on the wiki standalone, self-contained topics and concepts. Link between them. Follow aspects of the DITA model, more or less. Just remember that most wiki pages contain a lot of additional elements – headers, footers, various links, logos, navigation, and the like. Some of that just gets in the way. Luckily, most wikis have templates or themes that enable you to minimize the number of additional elements on a page.

Openess and authoringA wiki is as open as you need it to be. You can restrict who on your team can edit certain pages, or certain documents on the wiki. You can also restrict access to various wiki pages.

On the authoring and editing side of things, you can write directly in a wiki or use tools like:

• The Sun Wiki Publisher add-on for OpenOffice.org Writer

• WebWorks Publisher (although we've heard and read about mixed resultsfrom some people using the wiki export tool)

• The RoboHelp2Wiki extension for MediaWiki

Developers and other SMEs can review the help, add to it (if you let them), and provide instant feedback without having to pass files around or wasting paper by printing.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 7

That openness, as you know, can also extend to users. Remember what we said earlier about giving users what they want in the way they need it? Well, there's no reason why you can't have users editing the documentation on a wiki – changing something that isn't quite right, modifying or adding tasks that fit more closely with their workflow, and the like. Some technical communicators will blanche at that idea. Part of that has to do with what someone called the Wikipedia Syndrome. And part of that is wrapped up in some writers thinking that they're losing control of their documentation. Sorry to say this: the documentation that we work in isn't ours. We just write and maintain it. We create it for the users, not for ourselves. So why not let the users, whose insights into using an application or device can be as valid as ours, have a say too?

Wikis for the information that you've cut

Even if you use a more traditional form of online help, wikis are a great repository for all of the extraneous information that you cut out of a help system. You can set up a brand new wiki for that, or use a namespace in an existing wiki. A namespace is like a directory on a PC or a server. It's used to group wiki pages that contain similar content. If you're dealing with multiple products, then the namespace is your friend. With a namespace, you can have individual silos on the wiki for each project and never their twains shall meet. Unless, of course, you do some linking.

Blogs

Blogs are slowly becoming a way of delivering user assistance. Google uses the blogs for its various applications as release notes. Jing, a screencasting tool, delivers its help using Movable Type.

Blogs are easy to set up, and all you really need to use one is some space on a Web server and some software – most of it is Open Source; specifically the blog engine and a database like MySQL.

No matter what blog platform you're using, posting help topics using the blog paradigm is easy. You can use the built-in editor, or a desktop blogging client. There are even add-ons for some word processors, like the one for OpenOffice.org Writer, that allow you to create the content within a familiar environment and then publish it with a click. Before you do that, you can send the topic around for editing without having to print it or worry that the reviewer doesn't have access to the blog software.

That all sounds like a wild west, undisciplined way of doing things. And it can be. If you want a little more structure, think about using DITA. We're going to discuss this more towards the end of this talk, along with a demonstration.

As we mentioned a few moments ago, the folks behind Jing use a blog to deliver online user assistance. The main page contains links to important topics. And there's also navigation

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 8

at the top of the page to the main sections of the help. The how-to topics are are a mix of video and text. Most of the videos run at two minutes plus. If you don't want to wait that long, you can scroll down the screen and read the written procedure. It's all very short, compact, and to the point. As help should be.

As with a wiki, you can make the help context sensitive linking from an application to a specific topic or page on the blog.

Blogs: documentation for the small screen

At the beginning of this talk, we mentioned that some technical communicators need to create help for devices – like smartphones and netbooks – that have small screens. For those devices, help aimed at PC or laptop monitors just doesn't cut it. It's usually way too big and requires too much moving around to find information even on a simple page. Usability guru Jakob Neilsen reviewed the Kindle 2 book reader for the iPhone. The help, which is a page on the Amazon.com Web site, is one that's formatted a PC display. It's unsuited for a handheld.

A blog, though, can get around this problem. You don't have to create a separate, mobile-friendly blog for devices with small screens or tweak the CSS to add mobile capabilities. WordPress, for example, has a mobile plugin that detects a mobile device and makes a blog readable on that device. It's

easy to install, and actually is a mobile version of the blog and not just a Web page shoehorned into a small screen.

RSS

Who reads news and blogs with a feed reader? RSS is great for that, isn't it? RSS is also an excellent to link to information that supplements a help system. for delivering supplementary content to the user. This can be done within the user interface, or within the help. In fact, an upcoming release of WebWorks is said to integrate the ability to include RSS content in a help system. You can include feeds from a knowledge base, from a wiki, or from a repository of supplementary and overview documentation.

Take, for example, a company called uptime software, which develops a Web-based server monitoring tool. The company integrated an interesting feature that, among other things, added an RSS feed which linked to the latest articles in the company's knowledge base.

While we were working on this presentation, we were chatting with a colleague about embedded help. He said "Why not use RSS for that?" It's an interesting idea. We don't know how practical it is, though. For topic-based help, that would probably mean having to maintain one RSS feed per topic. That could get very unmanageable very quickly. On the other hand, if you plan to embed the entire help system in the user interface, then RSS can do the job.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 9

Tag clouds, search, and index

There's a lot of emphasis put on tagging, tag clouds, and search in the Web 2.0 world. All are potentially useful in online help.

Tagging allows you to assign keywords to a file or a topic. The tag cloud collects those keywords in one place, and adds a weight to each tag. In a tag cloud, some tags are larger than others. The size of the tag indicates the number of items (in this case, help topic) to which the tag has been applied – the larger the tag, the more items it's been applied to. With a click you get instant access to a list of all the files or topics that are tagged with a particular keyword. For this to work properly, you really need to create a good taxonomy. And that takes time.

Why is a good taxonomy important? A couple of companies at which we've been consulting recently use a wiki for internal documentation. The folks using the wiki have been tagging wiki pages. Unfortunately, everyone has been using the name of the product they're working with as their main tag. So, imagine clicking the tag NeoTrends – you wind up with a lot hits that you have to dig through.

As for search, we don't think that concept needs any introduction. It's a level or two up from the tag cloud, but you can still get more hits than you want or need.

Let's not forget the humble and venerable index. There's one

quote we love about indexes. It comes from a CS professor at Georgia Tech named Jim Greenlee, and he states that the index is the book's own search engine in the back.

Is there any one, best way to approach this? Definitely not. A combination of tagging, search, and a solid index are a good way to go in our opinion.

Index vs. tagging vs. ToCWhile developing this presentation, we talked with various colleagues about some of the ideas we were going to put forth. One of the questions that we heard more than once was "Why are you advocating tagging and indexing? Why not just tagging? Isn't that enough?"

It's a good question. Tagging can be a bit rough around the edges, even with a good taxonomy. You may get a lot of hits on a keyword – say, configuring. Some of the time, the topic that you want is at the top of the list. Sometimes, you need to search through the list of topics that a tag returns to find what you're looking for. With a well-developed index, you can quickly zero in on the specific topic you need in a matter of seconds. Probably far faster than when using a tag cloud.

And what about the good old ToC? Aside from the hierarchical structure and the sheer size of some of them, ToCs aren't granular enough. They'll take you to a certain level within a document or help file, but you'll only be in striking distance of the information that you want. You still have to go that extra distance to find what you need. In that

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 10

time, you could have found the information using a tag cloud or the index.

The times definitely are changing

The way in which people hunt for information has changed. Many people don't look for information in a linear fashion. What people are doing is looking for quick hits of information, to learn how to do something. You need to adapt what you're creating to the reading habits of today's users.

Here's a good example:

In 2008, Alan Porter of WebWorks blogged about how his daughter researched a project on Pearl Harbour. Porter's daughter used a combination of online and printed resources. First stop, not surprisingly, was Wikipedia. Next stop, at a friend's suggestion, was a social bookmarking site where she searched for relevant tags. When working with books, though, she flipped through the pages of the books and skimmed the contents for relevant information. Essentially, she was applying her Web browsing habits to dead trees.

In a situation like this, tagging is useful. It offers a quick way to find keywords. Tagging can, though, be a bit rough around the edges. As with a search, you get good hits with tagging but there's always superfluous information in the

mix. If created properly, though, an index is an excellent hybrid solution: you get the benefits of tagging and searching, but in a more refined and targeted form.

This really goes back to technical writing 101. Break things down. Keep everything as concise as possible. Make your text scannable. Write with the user in mind. It's easy enough to forget or ignore all of that.

Is help even necessary?

Before you give into that sudden urge to harm us, hear us out. We're not suggesting that you do away help entirely – that would throw a lot of technical communicators out of a job, and really put a dent in our business. What we mean is that is an actual, external help system really necessary? Why not embed help right into the application?

Admittedly, this has been done before. Usually with tool tips and field-level help – giving you a short explanation of what something is for, or what information you can enter into a field. Why not go a further than that and integrate more useful, more robust, and context-sensitive help into the user interface? Doing something like that is definitely more work up front, but it benefits the user in many ways. For example, it removes the need for the user to flip between the application and the help window.

Something like this works better with a Web-based

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 11

application where there's a little more unused real estate in the interface. A good example of this is Writeboard, a simple but useful collaborative writing tool. The text entry mode of Writeboard is a simple text editor. You can add basic formatting using a lightweight markup language called Textile. Of course, not everyone knows Textile; we use it occasionally but often need a refresher. In a Writeboard, you click a link to get a guide that illustrates the supported formatting markup. It doesn't open in a new window; it unfurls from the top of the Writeboard window.

Admittedly, Writeboard is a very simple application. It's possible to this with a more complex one, though. And you can make that help context sensitive by hooking in the topic or topics relevant to the tasks that users want to carry out in a particular window.

Doing something like this is easier (relatively speaking) in a Web-based program than on the desktop. A lot of GUI toolkits don't support the kinds of effects as well as popular Web development frameworks like AJAX or Ruby on Rails.

On the other hand, remember when we mentioned a feature in the application created by the company uptime software? The RSS feed of knowledge base articles. That feature also does a few other things. Like giving users quick access to tutorials and the support forums on the uptime Web site. There's also search engine that enables users to find content in the forums and in the knowledge base on the company's Web site.

Using video and audio If a picture is worth a thousand words, then a video should be worth several pages of them. It's a good concept – you can show and tell. Instead of relying on lengthy procedures, a video can walk a user through what needs to be done to complete a task. It's fairly easy to include video in online user assistance, especially if the help is HTML based. A short video, and a good tutorial video shouldn't be longer than a couple of minutes, only adds a megabyte or two (depending on the format that you use) to a help file.

An audio file is a little less flexible. It is possible to incorporate audio into documentation efforts, and it's been done with varying degrees of success. A few years ago, Apple released audio documentation for its VoiceOver accessibility tool. It was pretty much a spoken version of the manual; like listening to an audio book. At DocTrain West 2008, we all-too-briefly chatted with someone who incorporated short audio cues into online help. He developed short, spoken procedures or additional information or tasks for users to carry out.

Of the two, though, video is the superior option. Why? Video doesn't need to rely on words. It's easy to show someone how to perform a task or to demonstrate a new feature. Talking about it aurally navigating the listener through menus or other parts of the interface can take a lot of time and can be confusing.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 12

Writing as we speak

Earlier, we mentioned something that Tim O'Reilly said: users are looking for information in a style that's fun and engaging. Admittedly, O'Reilly was talking about the books his company publishes. Believe it or not, simplifying online help can also involve changing the style of writing that you use. Too often, the style of writing used in documentation is stiff, a tad formal, and can be verbose.

Don't get us wrong here. We're not stating or implying that you can't write. Sometimes, though, technical communicators get a bit complacent or just plain caught up in a set of writing standards. We have in the past. And those factors can get in the way of what's crucial when developing information for users.

We've probably all been taught that we need to write in a more formal tone. Admittedly, there's not a whole lot wrong with that. Technical writing doesn't have to be scintillating prose a la ... well, fill in the name of your favourite novelist here. But documentation doesn't have to be dry and boring like an academic tract or the articles that are published in a certain periodicals.

But why not writing as you'd speak? Clarity can come from writing in a more natural, conversational way. You might have to break a few rules of grammar. That shouldn't matter if your writing is clear and gets the point across succinctly.

A key to writing documentation that's easy-to-read while at the same time not dry is to write tightly. Keep it short and to the point. You'll have to choose your words very carefully to get the information that you need to get across in the shortest form. Keep it active. Keep it interesting.

You've probably heard people talking about documentation as a conversation. Why not interpret that literally? Write in the way that you speak. Well, without the umms, ahhs, and y'knows. Eliminate the pop culture references, clever turns of phrase, and jokey allusions that you might normally use when speaking to friends, family, or colleagues.

Assume that you're writing for the Web, even if you're not. One piece of advice that's given to aspiring Web writers is to limit sentences to 20 words. Preferably less. You don't need to view that as a hard and fast rule, though. If you need to writer longer sentences to achieve clarity, by all means do so.

Putting it all together

Well, a lot of it anyway ... We created a simple demo help system using WordPress. We chose WordPress because it's:

• The blogging platform that we're most familiar with

• Fairly easy to customize

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 13

• Open Source, as is the infrastructure it requires (a Web server, PHP, and a MySQL database)

• Flexible, and supports search, tagging, categories, and a tag cloud. To be honest, that's true of most other blogging platforms too.

The demo didn't take long to put together; about 15 or 20 minutes from installing WordPress and creating the MySQL database to importing the sample content.

What makes this possible is an add-on to WordPress: a DITA import tool. The tool, created by a software developer named Mike Little, adds an item to the WordPress import menu. To use it, first generate XHTML using the DITA Open Toolkit. Point the import tool to the top-level directory of your DITA output, and WordPress pulls in the files. As we found out, the DITA output has to be on the same server as your WordPress installation. It won't pull the output into WordPress from your hard drive.

You'll notice in the demo that we've added a static page for release notes and another one for feedback. The latter is an email form, which is available as a WordPress plugin. It's easy to set up and once the form has been configured you can forget about it. Well, at least until someone uses that form ...

The DITA import tool does a good job of separating concepts and tasks – as you can see from the menu along the top of

the page. The conepts and tasks aren't mixed together. Users don't have to peek at the concepts unless they want to. That said, each topic contains links to related concepts as just in case the user needs to get some background information. That information isn't intrusive, though.

One really useful aspect of this tool is that when you need to update your help, all you need to do is reimport it. The tool checks for updated content and seems to leave unchanged topics alone while overwriting topics that have been modified and adding new ones.

The drawback? The import isn't always perfect. You may need to edit the topics to fix some formatting issues and to remove the titles – they're both in the title field of the WordPress document (where they should be) and in the body of the document.

If you don't use DITA and want to add a little Web 2.0 to spice to your help, WordPress and the DITA import tool could be an excuse to move that way.

Drawbacks of what we've discussed

That all sounds interesting, doesn't it? What we've discussed definitely is interesting. It can be a great way to deliver online user assistance. It would be nice if what we've been talking about was the answer to all our online help authoring and deployment wishes and dreams. But as with any other

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 14

solution, there are a few drawbacks.

First off, what happens if some your users are behind a restrictive firewall? If you've shunted certain parts of your user assistance to a server somewhere else on the Web, then they might not be able to get access to it. That could definitely be frustrating.

Not everyone wants video as part of their documentation – they want information now, and don't want to wait a couple of minutes to watch a walk through of what they need to do. Here's an example: Scott recently bought a BlackBerry. To expand the memory, he bought a microSD card. Scott decided to to compare what was more effective: the printed instructions for inserting the card, or a video of the same by the folks at Crackberry.com. The video was just over three minutes long; it took Scott less than that to find the instructions that came with his phone and to do the job. So, sometimes, going old school works better.

Some software shops need to worry about translation and localization. That goes not only for their wares, but for the user assistance too. If, for example, you're using a blog to deliver user assistance, then you have to maintain not only separate versions of the blog software in the languages that you support, but also perhaps separate database instances. Video and audio add another layer of complexity. Scripts need to be translated into the target languages. Then, you need to do voiceovers in those languages. If you don't have the linguistic talent in house, then those tasks need to be

farmed out. Just watch your costs soar.

There's always the problem of institutional inertia. Right now, we’re in something of a transition phase when it comes to delivering and using help over the Web. Firms are starting to become more and more aware of the possibilities of using the Web to deliver timely documentation, but only a minority are making any moves to fully exploit those possibilities. While we’d love to see more traction in this area, we also realize that the transition will take time. A number of development shops do make updates to documentation available online, but not all users takes advantage of this. And we still have to deal with the customers who have very restrictive policies about downloading or receiving pushed information.

Conclusion

We spend so much time worrying about the usability of the application that we gloss over the usability of the user assistance that’s included with the application. It doesn’t have to be that way. Help should be simple, flexible, and designed for the needs of the user. Doing that is definitely possible. But it's up to us. We need to focus on how to move from being a content builders to a content architects.

That move won't be painless but it will be worth it.

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 15

Contact Us

Web site:

http://www.dmncommunications.com

Email:

info@dmncommunications.com

Blog:

http://www.dmncommunications/com/weblog

Podcast:

http://dmn.podbean.com

© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 16