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 FAQs
-
sometimes, even after the support team pointed users to the appropriate FAQ answers, the customers remained uncertain of the facts
-
the 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 hoped
-
support 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.
Georgina LaidlawGeorgina has more than fifteen years' experience writing and editing for web, print and voice. With a background in marketing and a passion for words, the time Georgina spent with companies like Sausage Software and sitepoint.com cemented her lasting interest in the media, persuasion, and communications culture.
