Blog Archives

WritersUA 2011 – Best practices for embedded UA

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Wednesday Scott DeLoach presented a great session called “Best practices for embedded UA“. This blog post is derived from the notes I made during the session. If you find any inaccuracies, they’ll be mine.

Scott gave us a set of guidelines for writing embedded user assistance (that’s help text and other information that appears as part of the UI) and showed us a number of sites that follow those best practices. He gave us guidelines on:

  • Writing the content of the user assistance
  • Getting user feedback
  • Allowing users to customise the user assistance they see
  • Encouraging users to learn
  • Using HTML5

Writing the content of the user assistance

In this section Scott focused on three things:

  • Persuading, motivating and communicating
  • Remembering that writing is a conversation
  • Integrating content from other sources

The Bank of America‘s online credit card application form is a good example of persuading and motivating.

  • At the top, the wording sets the expectation of time, telling you that you will receive a response in 60 seconds.
  • They point out that the communication is secure, which is a big concern of many customers.
  • When asking about citizenship/residence status, they give you a link called “Why do we ask for this?” That’s just the question people are likely to ask.
  • On the right, a panel contains a list of more questions that people are likely to ask. Instead of per-field help, the questions are much more advanced. is a good example of using writing as a conversation. This site can take advantage of the fact that the interaction is a more friendly one and a less formal one than online banking. For example, the popup on the password box says “Shhhhh! Your secret’s safe with us” before giving help on how to find a forgotten password. It’s OK to be fun and informal when the situation allows it.

Scott showed us a screenshot from Dreamweaver CS5, a good example of integrating content from other sources. At the bottom of the screenshot is a tab labelled “Reference”, where they integrate content from O’Reilly. You don’t have to write all your content. If content from other sources is good, use it.

Getting user feedback

Scott covered the following areas:

  • Allowing users to add comments
  • Providing alternative UA options
  • Requesting feedback
  • Ranking popular topics

An example from illustrated how you can allow users to add comments, and how useful this can be. There’s a section called “Community Content” where people can add their own information. This is really useful information, and is not filtered by Microsoft. The contributed information that Scott showed us was slightly critical about a feature provided by Microsoft, but the information was also really useful to other users.

The American Express gold card online application form is good at providing alternative UA options. There’s an area on the right called “Have a question? We can answer it right now,” showing a photograph of a smiling person. Scott says that the website will only show this particular text if the online support people are available right now to chat. Otherwise it will say something like, “Send an email”.

Some people don’t want to use the online information. They have the option to print the information, or to chat to someone on the phone. Not everyone is comfortable with using computers.

Talking about requesting feedback,  Scott showed us an example of a feedback form from, where people could fill in two yes/no answers, a graded answer (“how useful was this topic”) and a free-form text box. Scott remarked that it was a good form, because it only asked a few questions.

Scott really likes the example he showed us of ranking popular topics. The example came from Apple’s tech support knowledge base. They use scripting to find out which parts of the knowledge base people go to most often, and then they list the most popular topics. Scott likes the accessibility of this, and the wording – the use of the word “popular”, which makes readers feel good even if they’re looking for the answer to a problem. Also, what Scott finds the most impressive, is the “top searches” section. This is a great way to teach people how to do more complex searches.

Allowing users to customise the user assistance they see

Scott covered ways to allow users to:

  • Select a language
  • Ask their own questions
  • Reuse content
  • Turn off automatic user assistance

An example from the Carnival ship shows the usefulness of allowing users to select a language. The page Scott showed us is only visible once you have already booked in for a cruise. The site does a good job with callouts, per field, such as username and password. They explain the logic of the field and give you an example. There’s a lot of instructional information. You can choose another language, and everything on the page is translated, including the instructional text.

Scott remarked that he would prefer a bad translation rather than nothing. Even a part translation, or a Google translation, is better than nothing at all. Let people know that you’re using some sort of machine translation. They’ll be grateful for anything at all.

Another example showed a technology that we can use: Google’s translation API. Scott gave us this URL as an example:

From Sarah: I’ve done some searching and found some useful blog posts about this technology and how to use it without going to Google itself: How to Translate PDF & Word Documents with Google Translation, and Add Language Translation to your Website – Tutorial.

Scott noted that these technologies are improving all the time. Compare them to OCR technology, which was horrible at the start but is now really good. Big companies like Google are spending a lot of time on such technology and we should keep an eye on it.

On the subject of allowing users to ask their own questions, Scott showed us an example from the Washington Post website. In the example he showed us, you could highlight a term (such as a person’s name) and see a popup containing additional information about that term or person. This is similar to Netflix, when you hover over a movie. The Washington Post site uses an application called Apture to make this happen.

Users are beginning to expect this sort of rapid information. We should provide it too.

Scott showed us an example from MadCap’s software knowledge base, to illustrate how we can allow users to reuse content. MadCap provides a number of buttons for Twitter, Facebook, Favourites and Print. You can reuse the content in Twitter and Facebook. People want to do this sort of thing, so we should provide them with the opportunity. Also, who knows what people will do when we provide these features? People start using them in all sorts of creative ways.

A lot of people, especially the expert users, want to turn off the automatic user assistance. Some people like to learn by doing it on their own. Some people get very frustrated if we constantly try to help them. Give them a way to turn it off. For example, eBay has the option “Don’t show me this again”.

Encouraging users to learn

Scott spoke about these techniques:

  • Encouraging success
  • Encouraging exploration
  • Challenging people

If new users find that they can do something immediately, that’s essential for their success.

An example from Windows Live: Signing in to the Microsoft sites, the first thing you do is create a password. They tell you about the strength of the password, and a graphic representation of how strong your password is. You feel like you’ve achieved something if your password gets the green light.

Scott showed us a travel website,, that is great at encouraging exploration. The site has nine areas. Typically, most people go to only specific parts of the sites, such as car hire, flights, and so on. There’s a link that encourages you to spend a few minutes exploring the other features, to find awesome travel deals. There’s also a graphical representation of how much of the site you have explored so far, encouraging you to try new parts of the site.

An example from Intuit shows how you can challenge your users. They display a daily quiz for the “educated investor”. As you’re going through the site, you notice the question. Just one question per day. It motivates you to see if you can answer it correctly, check your answer, then even come back the next day for the next question, and get more involved in the site.

HTML5 techniques

Scott talked about:

  • Adding subtitles to instructional videos
  • Forms
  • Editing content
  • Saving content

Subtitling is Scott’s favourite, the feature he thinks is coolest. Subtitle files are “.srt” files. If you have a foreign-language movie that you’ve downloaded, do a Google search for the related “.srt” file. Put the file in the same folder as the AVI or MPEG file, and the player will usually find it.

Now, with HTML5, you can write a .srt file yourself. They’re very easy to write, says Scott. Then you can integrate it into your movie.

In HTML5, add the “video” element to include your video on the page. Include two script elements and a div

See Jan Gerber’s jQuery-based script to match an srt subtitle document to an HTML5 video:

When designing HTML forms:

  • You can have fields that are required, using the “required” attribute.
  • Validating input fields. You can give fields a type, that will prompt automatic validation. You can also build your own validation.

You can allow users to edit the content of a web page. Specify a new attribute, *contenteditable=”True”*. You can apply the attribute to any element, such as a paragraph. People can then click the content in that element and change it.

You can then save the edited content. Scott showed us some sample code. Typically, you’re saving it to the user’s local computer. The mechanism is similar to cookies, but much larger.

In a previous blog post, I covered some of this material from Scott’s earlier talk on HTML5: WritersUA 2011 Tuesday – HTML5.

My conclusion

Thank you Scott for yet another information-packed, engaging session!

%d bloggers like this: