If you work on a new-concept website—that is, a website that doesn’t
follow an established format like an ecommerce site or a blog—producing user
documentation might be the last task on your mind. Yet for sites that
present processes unfamiliar to users, quality documentation is
crucial.
Looking around at popular new-concept sites, you’d be forgiven for
thinking the opposite. The Twitter help content informs users the service
automatically shortens long URLs—except it doesn’t, and for first-time
users, that’s confusing and frustrating. Similarly, I’m unable to access my
Facebook wall from Facebook’s home page (logged in) via the My Wall link, or
even just Wall; instead I have to click on my own name to access My Wall. It
took me some time (and grumbling) to work that out the first time.
Though no one seems to question it, I expect these kinds of issues
arise because developers and usability specialists who develop these sites
write the user documentation—by which I mean all user-focused content, from
detailed FAQs to word-by-word site vocabulary—associated with them. Yes,
your development team can create good, clear, useful user documentation, but
as these examples show, it takes some finessing.
The benefits of good user documentation are manifold: as well as help
people use the site and its associated services successfully, increase user
satisfaction, and promote brand loyalty and word of mouth, it can also
reduce your support costs and bolster your position as the clear leader in
your niche.
This article assumes that you’re planning to use resources in your
existing development team to create user documentation for your site. It’s
primarily targeted at people launching new-concept sites, but
these techniques will work no matter what your site is about, and regardless
of whether or not you’ve already written user documentation.
Using the recent redevelopment of Flippa.com’s user documentation as a case
study, we’ll step through the key considerations your team will need to
address in developing user documentation that works. First, we’ll discuss
the most obvious issues that indicate that your user documentation could be
improved. Then we’ll break down those problems, to identify the linguistic
and conceptual tools your team will need to produce good documentation.
Finally, we’ll explore the techniques your team can use to apply those tools
in the development (or redevelopment) of user documentation that is actually
helpful.
There’s usually one crucial piece of evidence that reveals that user
documentation is failing to do its job: support queries.
A few months after the Flippa.com site launched, the support team
found that:
customers were continually asking the same questions—questions
that were answered in the site’s FAQssometimes, even after the support team pointed users to the
appropriate FAQ answers, the customers remained uncertain of the
factsthe augmentation of the site’s transaction and activity pages
with tooltip-style help information didn’t appear to be alleviating
user confusion as much as Flippa had hopedsupport queues (and support costs) were growing as site usage
expanded, since more users were asking the same basic questions every
day, while more experienced users were adding advanced questions to
the queue.
Flippa management had identified some help content that could have
been clearer, and felt that the voice and tone of the user documentation
was inconsistent; it had been written by a number of team members at
different times, and was frequently being tweaked by them in an effort to
make the information clearer.
There are other indications that your user documentation requires
sharpening. High refund and return request rates may suggest that users
are unsure of what they’re getting when they hand over their hard-earned
dollars to you. Reviews of your site or service, or online chatter, can
reveal problems with consistency and clarity you may have been unaware of.
Usability testing may prove that your interface provides cues to users
that are at odds with the information in your user documentation.
Once you have an inkling that your user documentation is lacking,
someone—you, a team member, or a usability or content specialist—will need
to look at it more closely: compare what’s in the Help, demo, or FAQ
content with the actual processes and language used on the site itself,
and note any inconsistencies.
The goal here is to gain an idea of the extent of the problems. You
might find that one particular FAQ page is confusing in its terminology,
and you may be able to rectify your overweight support queue significantly
by rectifying that issue. More likely, though, you’ll find a range of
issues that need more detailed attention. This was the case with the
Flippa website.
The Flippa site seemed to be laboring under the common burden I
mentioned earlier: the user documentation had been written by people who
knew what they were doing—the same people who built the site—but they were
trying to communicate such concepts to people who were far less familiar
with them—the site’s users.
It can be difficult for developers and designers who are in the
thick of it to step back and write content for people who know nothing
about the site—especially when the site’s launch is looming and there are
a billion other make-or-break tasks to do. Yet if you want your tech team
to write user documentation, this is what they’ll need to do.
If you’re writing user documentation from scratch, or you need to
overhaul existing documentation thoroughly, there are a few tools that can
make the job a success. If you’ve identified a number of issues with your
existing user documentation, you may find they relate to some of the tools
we’ll discuss in this section.
In any case, when you’re preparing to create user documentation, the
first step is to take a good look at the site’s target audience or
userbase. From there, you can develop a site or concept vocabulary and
standard phrasing, all of which you’ll compile into a comprehensive
content style guide.
Unlike your site’s development team, the userbase of a
new-concept site may be unfamiliar with the site and the concept
it presents. Site usage statistics are a common starting point for
defining a site’s userbase. A look at Flippa’s usage stats indicated
that there were more males than females, more younger people than older
people, and a large percentage of users from countries outside the USA,
many of which had a first language other than English.
Beyond this, though, Flippa had identified that a significant
portion of its userbase seemed to have little or no experience with the
concept of online auctions (or, indeed, the details and language of
auctions). On discussion, it was decided that buyers formed the primary
audience, and sellers the secondary audience. If we had to prioritize
one group, it was buyers.
When we considered this information in light of the site
generating monetary transactions, the Flippa team knew that their user
documentation had to create a sense of security and present the site as
an established, respected authority. The documentation had to
communicate clearly and make the details as easily understood as
possible—because of our non-native English-speaking users without
auction experience. These users had to comprehend the information
quickly and thoroughly enough that, rather than just leaving, they felt
confident to start buying and selling online property through the site
immediately.
Once you have a clear idea of who you’re writing the user
documentation for, you can start to look at some of the key elements
that define your new-concept site, and devise standard names for them.
Nailing down the language of your concept up front will make it much
easier to write consistent, comprehensible user documentation going
forward. It can also help you improve the usability of your interface
for the betterment of your bottom line.
Let’s look at an example. Flippa is, primarily, about auctioning
websites. This is indicated in the site’s header, shown in Figure 1, “Flippa.com’s home page header”.
This is fine from a branding perspective. But as they browse the
listings, buyers will come across auctions that aren’t, well, auctions.
They’re private sales, and they differ from auctions in terms of their
pricing, bidding, bid acceptance and rejection, and other processes. As
Figure 2, “A private sale listing on Flippa” shows, even the listing page
interface differs from the standard auction interface, shown in Figure 3, “A public auction listing on Flippa”.
To add to the confusion, Flippa’s listing-specific search
function, shown in Figure 4, “Flippa search function mentions auctions only”, doesn’t refer
to private sales at all—it only talks about auctions. Does this mean
that no search results include private sales? Are private sales some
special, restricted-access type of auction? These are the kinds of
questions that abound in the minds of users who stumble across a sale
type that they haven’t seen mentioned elsewhere.
Sellers were in a similar boat. The site referred almost
exclusively to auctions throughout its interface and basic help pages
(like the one shown in Figure 5, “Flippa’s basic help refers to auctions only”), yet when listing
their online property, sellers were asked whether they wanted to sell it
at auction or in a private sale, as Figure 6, “Flippa’s listing page asks users to select a sale type” shows.
This content, located in the midst of the listing process (the
point at which the Flippa team wanted to reduce friction as much as it
could), was one of just two pieces of content we could find that
indicated some difference between these two sale types. They weren’t
defined in the site’s help content, but a little more information was
provided on the How to Sell Your Website page, shown in Figure 7, “The only other content differentiating between auction and
private sale”.
Transaction sites focused on removing friction from sales or
sign-up processes must reduce the confusion that arises from these kinds
of omissions. Developing a standard concept
vocabulary—nomenclature for new or site-specific concepts—to
use throughout the site and its user documentation is the first step in
solving this problem.
For Flippa, we decided to refer to the two types of selling
approaches separately: as public auctions and private sales. We needed
the private on private sales so that we could use
variations of the word sale—like selling and seller—where we needed to.
We considered calling public auctions just auctions, but the research
we’d compiled on our audience indicated that the clearest possible
differentiation would be most helpful for users. If private sales were
always private sales, leaving the public out of public auctions would
risk confusing users who might suspect, if no indication was given, that
perhaps auctions could be public or private.
The next step was to develop unique language for each of these
concepts. So users would bid and place
bids in auctions, but make an offer in
private sales. Both types of transaction would have an online
property listing, which we could refer to simply as a
listing, because we wanted to avoid being tied to
using the lengthy private sale or public
auction every time we talked about selling stuff on the site.
We would, however, reserve listing page for times
when we needed to refer to the actual interface of the listing.
As you can see, developing a vocabulary for your new concept can
be tricky. As well as working out what makes sense to your userbase,
it’s important to get buy-in from stakeholders. Think again of
Facebook’s Wall. When you overhear someone say, “He wrote on my wall,”
it’s an endorsement for Facebook. You know the person’s talking about
Facebook, because the word “wall” used in an online context has become
inextricably associated with that site.
This is a crucial point to keep in mind: when you’re creating a
new concept, you have the chance to form the language around that
concept. While senior management may deliberate for months over a brand
name, the naming decisions you make to support the communication of your
concept may well end up becoming central to that brand. Choose your
words wisely. Discuss them with stakeholders. Test them with users. Do
whatever you need to to be confident that your concept vocabulary is on
the mark.
Once you’ve developed your concept vocabulary, it’s time to turn
your thoughts to the phrasing used with those carefully selected terms.
Think of your concept vocabulary as a set of building blocks, and the
supporting phrases as the glue that will hold your concepts
together.
The wording around Flippa’s reserve price concept is a good
example. The reserve price is the minimum price the seller wants for an
online property. Users have to understand this in order to grasp other
concepts to do with bid values, bid acceptance, and so on. In reviewing
the user documentation, we found that phrases like equal to or
exceeding, greater than or equal to, and
is equal to or more than came up very often—almost
as often as the concept of the reserve price itself. Figure 8, “Wording around the concept of the reserve price” shows just one example from the reserve
price help content.
For a user who’s unfamiliar with the site and struggling to keep
the concept of a reserve price in their head, it helps if we use
consistent wording with that concept. Consistent language reduces the
chance for distraction, and makes it easier for information to be
absorbed. So, each time users are presented with the idea of a bid that
meets or exceeds the reserve price (what was that
again?), we want to avoid them being preoccupied with working out if
greater than or equal to and equal to or
more than are the same.
For this reason we developed the support phrase equal to
or more than, and committed to using that every time we spoke
about the reserve price being met or exceeded. This meant users could
learn that phrase just once, and understand what it meant. They’d then
be able to apply the knowledge every time they came across that phrase
subsequently. The consistent language freed up users to focus on
understanding the bigger-deal concepts that were unique to our
site.
One consideration to keep in mind as you develop this support
phrasing is the makeup of your audience, and hence, the voice you want
your user documentation to carry. We could have used the simpler
equals or exceeds phrasing to talk about reserve
prices on Flippa. It’s shorter and more concise than equal to
or more than—a big bonus when the phrase is used frequently
across many detailed pages of information. Also, we wanted the content
to have a professional voice, and equals or exceeds
definitely sounds more professional than the high-school terminology of
equal to or more than.
Yet, for audience-related reasons, we opted for equal to
or more than. Firstly, it sounds friendlier, and trust was a
big factor for us to focus on. Secondly, some might argue that “exceeds”
hints at excess—that it sounds expensive—and we wanted to convey that
flipping online property was accessible to everyone. We also felt that
this phrasing would be familiar to more people, given the youth of our
userbase and the number of non-native English speakers: “more than” is
more likely to be understood than “exceeds” by that type of user. In
short, we sacrificed word count for clarity, and decided we’d use other
opportunities within the text to convey the site’s professionalism and
authority.
Every choice you make at this point should be about achieving the
greatest clarity for the greatest number of users. If you think that
perhaps the emphasis on non-English speakers is unjustified for a site
whose audience is, after all, predominantly based in English-speaking
nations, remember that we’re not dumbing down the content: these small
word selections are simply maximizing accessibility and
comprehension.
Regardless of whether you have one person or ten working on the
user documentation, it’s essential that you compile all the decisions
you’ve made about concept vocabulary and standard phrasing into a style
guide, along with directives about capitalization of proper nouns,
punctuation of abbreviations, and treatment of jargon and spellings (for
example, Flippa uses “website” as one word, not two).
This reference guide will allow designers, developers, and support
staff to communicate to users using the same vocabulary and language. It
will enable you to hand user documentation and support responsibilities
to new team members in a simpler way. It will help you establish a voice
and persona for your brand, and develop a loyal, enthusiastic following
more easily.
Written By:
