Think Simple: A Fresh Approach to User Assistance
By: Aaron Davis and Scott Nesbitt
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

working with standard tools, and yet couldn't get the help to
Note: Throughout this presentation, we'll be using the terms come out just right – it would work well on some of the
help, online help, and user assistance interchangeably. supported devices, but not others. She eventually turned to
XML. Now, there is only one XML document for all supported
Yesterday, today, and tomorrow platforms.
Online user assistance as it was (and often is)
Envision, for a moment, online help as it was. And as it is.
Can you think of any major differences? What do you think Too often, help is a copy of the user manual in another
about when you hear the words online help? format – HTML Help, WebHelp, WinHelp, or whatever. Help
authors may choose to remove graphics and change cross
User assistance hasn't radically changed over the years. references to hyperlinks, but users are still essentially getting
Sure, delivery formats have changed, there are some cool a version of the manual when they press F1.
single sourcing tools available, and we can re-purpose
content for a wide variety of uses. But the structure and Why is it done this way? A variety of reasons. For some,
design of most help systems and the type of content that there's a perception that this is the way it's always been
they contain, is often the same as it was in 1995. And that's done. If it ain't broke, don't fix it. That doesn't mean things
where user assistance has fallen down - by not meeting the can't improve. Inertia from management can also be a
needs of today's user. problem. There may be time constraints – short development
cycles require some technical communicators to hammer out
On top of that, many technical communicators are documentation quickly and as best they can based on those
developing user assistance for more than just the monitor on constraints. They might have to forego certain niceties in
a desktop PC or a laptop. Consider smartphones and mobile order to get the job done.
applications. User assistance for a broad range of
functionality must be delivered within a limited amount of Case in point: when we worked at a large enterprise
screen real estate. The online help paradigm as we software firm, the PDF output did double duty as the printed
commonly know it is simply not suitable for these platforms. manual and the online help for the application. Help was
triggered through hooks built into the app that launched
Take, for example, Viigo. It's an RSS client for various Acrobat Reader. Users weren't getting a true online help
smartphones. The technical writer at Viigo spent a lot of time 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 With both, it's faster and easier to build purposeful help
too much information for the reader to wade through to get to directly than to first create a guide and then do the usual
single sourcing magic.
what they need.
Here's a good example of this: the help for Viigo, the mobile
Is single sourcing always the path to take?
application that we mentioned earlier. When the technical
Let's talk about single sourcing for a moment. The way many writer at Viigo started working on the help, she ran into a
of us do it is first write your content in FrameMaker or Word number of issues:
or whatever. Then, pull those files into a help tool like
RoboHelp or WebWorks. From there, output the help. Doing
Using a standard single sourcing tool, she created tri-
•
that is familiar. It's comfortable. But in some cases, it's not
paned HTML help. There were too many panes, and
the best solution.
the help didn't render well on a mobile device.
Sometimes, though, that single sourcing method isn't the
There are multiple screen sizes for mobile devices,
•
best solution. Instead, why not author the user assistance
and what looks good on one may not look good on
directly? Say you're documenting a simple desktop or mobile
another.
application, or one that's served over the Web. In these
Navigation was a problem, and she couldn't use a
cases, having a separate printed or PDF manual doesn't •
nested table of contents.
make all that much sense.
With the simple application – and by simple, we mean After a lot of thought and consultation with the company's
something that's not as monolithic as Word but not as Web designer, she wrote the help using XML and on-the-fly
rudimentary as Notepad – chances are users won't look at XSLT tranforms dynamically output the help to all of Viigo's
the manual. OK, that's not so different from normal ... supported platforms.
Seriously, though, they're more likely to press F1 to get
assistance.
Another path: think simple
Many Web-based applications are more complex than the
Simple. It's not a four letter word, but it's often treated like
simple desktop or mobile application. In this case, the user
one. Simple doesn't mean incomplete, inadequate, or
assistance is delivered over the Web.
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 any material that disrupts the main flow of the user
question: assistance, so be it.
Help should be about what users want to do. The information
Are we giving readers the information they want, in
that users need is often broken up by pages and pages (or
the way they want and need it?
topics and topics) of introductory matter and background
material. We've found over the years that the people using
That one question is a common thread in our thinking about
an application or gadget don't want or need that information.
user assistance. In a lot of cases, the answer to that question
Well, maybe at first they do – it can come in handy when
is no.
they're getting the lay of the land. But as they progress with
using an application or device that supplementary and
Let's consider the purpose of user assistance. It's supposed
background information just gets in the way of them learning
to take users from that stage of fumbling in the dark to a
how to get things done.
level of mastery. Or, at the very least, put them on firmer
footing and start them down the road to mastery. The key to
Think about this: when someone sends you a Word macro,
user assistance is showing users how to do things, and not
what do you want to do? Install that macro. Run the macro.
telling them what a piece of software or hardware can do.
Make it accessible via a toolbar button. You probably don't
care about what a macro is and all the wonderful (or not)
1.0 + 2.0 = 1.5? things that a macro can do.
Publisher Tim O'Reilly summed it up well when he wrote:
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. People are looking for advanced tips and tricks.
The main thrust of that person's argument was a) they liked They're not looking for the basics. They're looking for
having excess information in the help, and b) a help system things that will give them more of an edge. And they're
without that information isn't complete. looking for it in a style that's fun and engaging.
This goes back to what we said earlier: simple doesn't mean It's within your grasp to do just that.
incomplete. It means giving users the information that they
need, in the way that they need it. If that means removing
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 4

Start cutting of the user, it doesn't mean that it's not there.
Overview and explanatory information can be important.
A key idea behind thinking simple is getting rid of anything
There are ways in which you can separate it from the meat
that doesn't advance the goal of the user. And that goal is
of your user assistance. How? How about:
learning how to get things done in the fastest, most efficient
way. In order to do that, you need to cut away anything that
Use popups or mouseovers to define terms or give a
•
the user won't need.
little extra background information
• Have it appear or disappear with a click – most help
Before getting the scalpel out, do some planning. Take an
authoring tools enable you to do something like this
inventory of all of the content in your user assistance that
• Put the information somewhere else – a
doesn't explain how to do something. Then, consider:
supplementary help file on the user's network or hard
drive, or somewhere on the Web – say, a wiki or a
1. What you can keep in the help
blog. We'll talk more about this soon.
2. How to make that content unobtrusive within the help
A little deforestation might be in order
3. Where you can move that content if you don't want it
in the help 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
4. How users will access that content from the help
linear narrative flow – beginning, middle, and end. But who
reads a manual from beginning to end? OK, we all probably
Doing all of that might take a while, but those definitely are
know one or two people who do. They're the exception.
worthwhile steps. Then, you can start cutting.
We're deep in the age of hypertext. And hypertext makes
What's up front that kind of linear narrative obsolete. In fact, hypertext
probably follows the thought and usage patterns of most
So, what's the first thing that should go? You've probably
users better than the tree-like flow of the standard TOC.
guessed what it is: overview and expository information. Any
Remember that we're not telling a story with documentation.
list of \"what's new\". That information isn't going to do much
We're showing users how to get things done. And that's what
to aid the user in gaining proficiency or mastery. But
good help does.
remember that simply because the information isn't the face
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 5

Organization
But the Web changed the rules quite quickly. And Web 2.0
even more so.
More than anything else, the key to good user assistance is
organization. No matter how good your information is, if it
The term Web 2.0 is overused, and we utter it with caution.
isn't organized properly it's going to be difficult to use. But the concepts of Web 2.0 offer some very interesting
options for user assistance. Those options are another key to
So, what's the optimal method of organization? There isn't thinking simple. You can quickly adapt them to your
just one. The way in which we prefer to do it is to group simplified user assistance.
similar tasks – for example, all of the topics on importing and
exporting data. You can structure the base of the hierarchy
Google or F1?
as a question like How do I ...? Or, you can simply have a
heading like Importing and Exporting, followed by a list of How do many people get help about these days? Do they
topics – for example, How to Export Your Documents. 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
Nothing revolutionary there. It's being done, but not often 2.0 when building your help.
enough.
We find that the following four aspects of Web 2.0 are well
suited for user assistance:
Web 2.0
Wikis
•
Well organized wiki pages can be an effective
Remember the days before the Internet was on computers? •
online help platform
Or the period in the early to mid 1990s, when it was still
something of a novelty: not all companies or individuals were They're also a great repository for background
•
online, or even had computers with modems. In those days, and explanatory information
the types of things that we're going to discuss next were
Blogs
pretty much impossible. And not just because of the Internet •
Easy to set up and maintain
and Web were new phenomena to many. The tools that were •
used to create online user assistance were ... well, they were WordPress has a DITA import tool (which we
•
relatively primitive. discuss later)
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 6

RSS like an online help system. Make pages on the wiki
•
Tagging standalone, self-contained topics and concepts. Link
•
between them. Follow aspects of the DITA model, more or
Wikis less. Just remember that most wiki pages contain a lot of
additional elements – headers, footers, various links, logos,
Let's start off by talking about wikis. We don't have to tell you navigation, and the like. Some of that just gets in the way.
how deeply wikis have become entrenched in the Luckily, most wikis have templates or themes that enable
documentation world. In fact, a lot of firms and many Open you to minimize the number of additional elements on a
Source projects deliver their documentation using wikis page.
alone. Wikis are a great way to publish full user manuals and
to get user assistance out to customers. One company that's
Openess and authoring
doing just that is Atlassian.
A wiki is as open as you need it to be. You can restrict who
on your team can edit certain pages, or certain documents
You might know Atlassian as the developer of the popular
on the wiki. You can also restrict access to various wiki
Confluence wiki. And Atlassian is one of those companies
pages.
that eats it own dog food. How? By publishing all of its
documentation on a public wiki, powered by Confluence of
On the authoring and editing side of things, you can write
course. But Atlassian is going one step further with a pair of
directly in a wiki or use tools like:
developer tools called FishEye and Crucible. They've
included icons in the user interfaces of those applications.
The Sun Wiki Publisher add-on for OpenOffice.org
•
Click an icon, and you're taken to the appropriate
Writer
documentation page on the Atlassian wiki. And it's not just a
single icon in the UI, either. The help is relatively context WebWorks Publisher (although we've heard and read
•
about mixed resultsfrom some people using the wiki
sensitive, with help icons beside elements on a screen.
export tool)
With a wiki, you can easily separate overview and The RoboHelp2Wiki extension for MediaWiki
•
background information from procedural and how-to
information. Because of that, it's easy to make the help
Developers and other SMEs can review the help, add to it (if
context sensitive linking from an application to a specific wiki
you let them), and provide instant feedback without having to
page. And there's no reason why you can't structure a wiki
pass files around or wasting paper by printing.
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 7

Blogs
That openness, as you know, can also extend to users.
Blogs are slowly becoming a way of delivering user
Remember what we said earlier about giving users what
assistance. Google uses the blogs for its various applications
they want in the way they need it? Well, there's no reason
as release notes. Jing, a screencasting tool, delivers its help
why you can't have users editing the documentation on a
using Movable Type.
wiki – changing something that isn't quite right, modifying or
adding tasks that fit more closely with their workflow, and the
Blogs are easy to set up, and all you really need to use one
like. Some technical communicators will blanche at that idea.
is some space on a Web server and some software – most
Part of that has to do with what someone called the
of it is Open Source; specifically the blog engine and a
Wikipedia Syndrome. And part of that is wrapped up in some
database like MySQL.
writers thinking that they're losing control of their
documentation. Sorry to say this: the documentation that we
No matter what blog platform you're using, posting help
work in isn't ours. We just write and maintain it. We create it
topics using the blog paradigm is easy. You can use the
for the users, not for ourselves. So why not let the users,
built-in editor, or a desktop blogging client. There are even
whose insights into using an application or device can be as
add-ons for some word processors, like the one for
valid as ours, have a say too?
OpenOffice.org Writer, that allow you to create the content
within a familiar environment and then publish it with a click.
Wikis for the information that you've cut
Before you do that, you can send the topic around for editing
Even if you use a more traditional form of online help, wikis without having to print it or worry that the reviewer doesn't
are a great repository for all of the extraneous information have access to the blog software.
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 That all sounds like a wild west, undisciplined way of doing
namespace is like a directory on a PC or a server. It's used things. And it can be. If you want a little more structure, think
to group wiki pages that contain similar content. If you're about using DITA. We're going to discuss this more towards
dealing with multiple products, then the namespace is your the end of this talk, along with a demonstration.
friend. With a namespace, you can have individual silos on
the wiki for each project and never their twains shall meet. As we mentioned a few moments ago, the folks behind Jing
Unless, of course, you do some linking. 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 easy to install, and actually is a mobile version of the blog
how-to topics are are a mix of video and text. Most of the and not just a Web page shoehorned into a small screen.
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 RSS
procedure. It's all very short, compact, and to the point. As
Who reads news and blogs with a feed reader? RSS is great
help should be.
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
As with a wiki, you can make the help context sensitive
the user interface, or within the help. In fact, an upcoming
linking from an application to a specific topic or page on the
release of WebWorks is said to integrate the ability to
blog.
include RSS content in a help system. You can include feeds
from a knowledge base, from a wiki, or from a repository of
Blogs: documentation for the small screen
supplementary and overview documentation.
At the beginning of this talk, we mentioned that some
technical communicators need to create help for devices – Take, for example, a company called uptime software, which
like smartphones and netbooks – that have small screens. develops a Web-based server monitoring tool. The company
For those devices, help aimed at PC or laptop monitors just integrated an interesting feature that, among other things,
doesn't cut it. It's usually way too big and requires too much added an RSS feed which linked to the latest articles in the
moving around to find information even on a simple page. company's knowledge base.
Usability guru Jakob Neilsen reviewed the Kindle 2 book
reader for the iPhone. The help, which is a page on the While we were working on this presentation, we were
Amazon.com Web site, is one that's formatted a PC display. chatting with a colleague about embedded help. He said
It's unsuited for a handheld. \"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
A blog, though, can get around this problem. You don't have would probably mean having to maintain one RSS feed per
to create a separate, mobile-friendly blog for devices with topic. That could get very unmanageable very quickly. On
small screens or tweak the CSS to add mobile capabilities. the other hand, if you plan to embed the entire help system
WordPress, for example, has a mobile plugin that detects a in the user interface, then RSS can do the job.
mobile device and makes a blog readable on that device. It's
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 9

quote we love about indexes. It comes from a CS professor
Tag clouds, search, and index
at Georgia Tech named Jim Greenlee, and he states that the
There's a lot of emphasis put on tagging, tag clouds, and index is the book's own search engine in the back.
search in the Web 2.0 world. All are potentially useful in
online help. Is there any one, best way to approach this? Definitely not. A
combination of tagging, search, and a solid index are a good
Tagging allows you to assign keywords to a file or a topic. way to go in our opinion.
The tag cloud collects those keywords in one place, and
adds a weight to each tag. In a tag cloud, some tags are
Index vs. tagging vs. ToC
larger than others. The size of the tag indicates the number
While developing this presentation, we talked with various
of items (in this case, help topic) to which the tag has been
colleagues about some of the ideas we were going to put
applied – the larger the tag, the more items it's been applied
forth. One of the questions that we heard more than once
to. With a click you get instant access to a list of all the files
was \"Why are you advocating tagging and indexing? Why
or topics that are tagged with a particular keyword. For this
not just tagging? Isn't that enough?\"
to work properly, you really need to create a good taxonomy.
And that takes time.
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
Why is a good taxonomy important? A couple of companies
on a keyword – say, configuring. Some of the time, the topic
at which we've been consulting recently use a wiki for
that you want is at the top of the list. Sometimes, you need to
internal documentation. The folks using the wiki have been
search through the list of topics that a tag returns to find
tagging wiki pages. Unfortunately, everyone has been using
what you're looking for. With a well-developed index, you
the name of the product they're working with as their main
can quickly zero in on the specific topic you need in a matter
tag. So, imagine clicking the tag NeoTrends – you wind up
of seconds. Probably far faster than when using a tag cloud.
with a lot hits that you have to dig through.
And what about the good old ToC? Aside from the
As for search, we don't think that concept needs any
hierarchical structure and the sheer size of some of them,
introduction. It's a level or two up from the tag cloud, but you
ToCs aren't granular enough. They'll take you to a certain
can still get more hits than you want or need.
level within a document or help file, but you'll only be in
striking distance of the information that you want. You still
Let's not forget the humble and venerable index. There's one
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 mix. If created properly, though, an index is an excellent
or the index. hybrid solution: you get the benefits of tagging and
searching, but in a more refined and targeted form.
The times definitely are changing
This really goes back to technical writing 101. Break things
down. Keep everything as concise as possible. Make your
The way in which people hunt for information has changed.
text scannable. Write with the user in mind. It's easy enough
Many people don't look for information in a linear fashion.
to forget or ignore all of that.
What people are doing is looking for quick hits of
information, to learn how to do something. You need to
Is help even necessary?
adapt what you're creating to the reading habits of today's
users.
Before you give into that sudden urge to harm us, hear us
Here's a good example: out. We're not suggesting that you do away help entirely –
that would throw a lot of technical communicators out of a
In 2008, Alan Porter of WebWorks blogged about how his job, and really put a dent in our business. What we mean is
daughter researched a project on Pearl Harbour. Porter's that is an actual, external help system really necessary?
daughter used a combination of online and printed Why not embed help right into the application?
resources. First stop, not surprisingly, was Wikipedia. Next
stop, at a friend's suggestion, was a social bookmarking site Admittedly, this has been done before. Usually with tool tips
where she searched for relevant tags. When working with and field-level help – giving you a short explanation of what
books, though, she flipped through the pages of the books something is for, or what information you can enter into a
and skimmed the contents for relevant information. field. Why not go a further than that and integrate more
Essentially, she was applying her Web browsing habits to useful, more robust, and context-sensitive help into the user
dead trees. interface? Doing something like that is definitely more work
up front, but it benefits the user in many ways. For example,
In a situation like this, tagging is useful. It offers a quick way it removes the need for the user to flip between the
to find keywords. Tagging can, though, be a bit rough application and the help window.
around the edges. As with a search, you get good hits with
tagging but there's always superfluous information in the Something like this works better with a Web-based
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 11

Using video and audio
application where there's a little more unused real estate in
the interface. A good example of this is Writeboard, a simple If a picture is worth a thousand words, then a video should
but useful collaborative writing tool. The text entry mode of be worth several pages of them. It's a good concept – you
Writeboard is a simple text editor. You can add basic can show and tell. Instead of relying on lengthy procedures,
formatting using a lightweight markup language called a video can walk a user through what needs to be done to
Textile. Of course, not everyone knows Textile; we use it complete a task. It's fairly easy to include video in online
occasionally but often need a refresher. In a Writeboard, you user assistance, especially if the help is HTML based. A
click a link to get a guide that illustrates the supported short video, and a good tutorial video shouldn't be longer
formatting markup. It doesn't open in a new window; it than a couple of minutes, only adds a megabyte or two
unfurls from the top of the Writeboard window. (depending on the format that you use) to a help file.
Admittedly, Writeboard is a very simple application. It's An audio file is a little less flexible. It is possible to
possible to this with a more complex one, though. And you incorporate audio into documentation efforts, and it's been
can make that help context sensitive by hooking in the topic done with varying degrees of success. A few years ago,
or topics relevant to the tasks that users want to carry out in Apple released audio documentation for its VoiceOver
a particular window. accessibility tool. It was pretty much a spoken version of the
manual; like listening to an audio book. At DocTrain West
Doing something like this is easier (relatively speaking) in a 2008, we all-too-briefly chatted with someone who
Web-based program than on the desktop. A lot of GUI incorporated short audio cues into online help. He developed
toolkits don't support the kinds of effects as well as popular short, spoken procedures or additional information or tasks
Web development frameworks like AJAX or Ruby on Rails. for users to carry out.
On the other hand, remember when we mentioned a feature Of the two, though, video is the superior option. Why? Video
in the application created by the company uptime software? doesn't need to rely on words. It's easy to show someone
The RSS feed of knowledge base articles. That feature also how to perform a task or to demonstrate a new feature.
does a few other things. Like giving users quick access to Talking about it aurally navigating the listener through menus
tutorials and the support forums on the uptime Web site. or other parts of the interface can take a lot of time and can
There's also search engine that enables users to find content be confusing.
in the forums and in the knowledge base on the company's
Web site.
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 12

Writing as we speak
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
Earlier, we mentioned something that Tim O'Reilly said:
the point. You'll have to choose your words very carefully to
users are looking for information in a style that's fun and
get the information that you need to get across in the
engaging. Admittedly, O'Reilly was talking about the books
shortest form. Keep it active. Keep it interesting.
his company publishes. Believe it or not, simplifying online
help can also involve changing the style of writing that you
You've probably heard people talking about documentation
use. Too often, the style of writing used in documentation is
as a conversation. Why not interpret that literally? Write in
stiff, a tad formal, and can be verbose.
the way that you speak. Well, without the umms, ahhs, and
y'knows. Eliminate the pop culture references, clever turns of
Don't get us wrong here. We're not stating or implying that
phrase, and jokey allusions that you might normally use
you can't write. Sometimes, though, technical
when speaking to friends, family, or colleagues.
communicators get a bit complacent or just plain caught up
in a set of writing standards. We have in the past. And those
Assume that you're writing for the Web, even if you're not.
factors can get in the way of what's crucial when developing
One piece of advice that's given to aspiring Web writers is to
information for users.
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
We've probably all been taught that we need to write in a
writer longer sentences to achieve clarity, by all means do
more formal tone. Admittedly, there's not a whole lot wrong
so.
with that. Technical writing doesn't have to be scintillating
prose a la ... well, fill in the name of your favourite novelist
Putting it all together
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. Well, a lot of it anyway ... We created a simple demo help
system using WordPress. We chose WordPress because it's:
But why not writing as you'd speak? Clarity can come from
writing in a more natural, conversational way. You might The blogging platform that we're most familiar with
•
have to break a few rules of grammar. That shouldn't matter
Fairly easy to customize
•
if your writing is clear and gets the point across succinctly.
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 13

Open Source, as is the infrastructure it requires (a the page. The conepts and tasks aren't mixed together.
•
Web server, PHP, and a MySQL database) Users don't have to peek at the concepts unless they want
to. That said, each topic contains links to related concepts as
Flexible, and supports search, tagging, categories,
•
just in case the user needs to get some background
and a tag cloud. To be honest, that's true of most
information. That information isn't intrusive, though.
other blogging platforms too.
One really useful aspect of this tool is that when you need to
The demo didn't take long to put together; about 15 or 20 update your help, all you need to do is reimport it. The tool
minutes from installing WordPress and creating the MySQL checks for updated content and seems to leave unchanged
database to importing the sample content. topics alone while overwriting topics that have been modified
and adding new ones.
What makes this possible is an add-on to WordPress: a
DITA import tool. The tool, created by a software developer The drawback? The import isn't always perfect. You may
named Mike Little, adds an item to the WordPress import need to edit the topics to fix some formatting issues and to
menu. To use it, first generate XHTML using the DITA Open remove the titles – they're both in the title field of the
Toolkit. Point the import tool to the top-level directory of your WordPress document (where they should be) and in the
DITA output, and WordPress pulls in the files. As we found body of the document.
out, the DITA output has to be on the same server as your
WordPress installation. It won't pull the output into If you don't use DITA and want to add a little Web 2.0 to
WordPress from your hard drive. spice to your help, WordPress and the DITA import tool
could be an excuse to move that way.
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
Drawbacks of what we've discussed
email form, which is available as a WordPress plugin. It's
easy to set up and once the form has been configured you
That all sounds interesting, doesn't it? What we've discussed
can forget about it. Well, at least until someone uses that
definitely is interesting. It can be a great way to deliver online
form ...
user assistance. It would be nice if what we've been talking
about was the answer to all our online help authoring and
The DITA import tool does a good job of separating concepts
deployment wishes and dreams. But as with any other
and tasks – as you can see from the menu along the top of
© 2009 DMN Communications Think Simple: A Fresh Approach to User Assistance - 14

solution, there are a few drawbacks. farmed out. Just watch your costs soar.
First off, what happens if some your users are behind a There's always the problem of institutional inertia. Right now,
restrictive firewall? If you've shunted certain parts of your we’re in something of a transition phase when it comes to
user assistance to a server somewhere else on the Web, delivering and using help over the Web. Firms are starting to
then they might not be able to get access to it. That could become more and more aware of the possibilities of using
definitely be frustrating. the Web to deliver timely documentation, but only a minority
are making any moves to fully exploit those possibilities.
Not everyone wants video as part of their documentation – While we’d love to see more traction in this area, we also
they want information now, and don't want to wait a couple of realize that the transition will take time. A number of
minutes to watch a walk through of what they need to do. development shops do make updates to documentation
Here's an example: Scott recently bought a BlackBerry. To available online, but not all users takes advantage of this.
expand the memory, he bought a microSD card. Scott And we still have to deal with the customers who have very
decided to to compare what was more effective: the printed restrictive policies about downloading or receiving pushed
instructions for inserting the card, or a video of the same by information.
the folks at Crackberry.com. The video was just over three
minutes long; it took Scott less than that to find the Conclusion
instructions that came with his phone and to do the job. So,
sometimes, going old school works better.
We spend so much time worrying about the usability of the
application that we gloss over the usability of the user
Some software shops need to worry about translation and
assistance that’s included with the application. It doesn’t
localization. That goes not only for their wares, but for the
have to be that way. Help should be simple, flexible, and
user assistance too. If, for example, you're using a blog to
designed for the needs of the user. Doing that is definitely
deliver user assistance, then you have to maintain not only
possible. But it's up to us. We need to focus on how to move
separate versions of the blog software in the languages that
from being a content builders to a content architects.
you support, but also perhaps separate database instances.
Video and audio add another layer of complexity. Scripts
That move won't be painless but it will be worth it.
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
© 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