Embedded User Assistance

=============================================================

Publishing Details

This article was published in the newsletter of the STC Regional Conference that was held in Pune on June 28, 2015. 

=============================================================

Foreword

Recently, I randomly picked a handful of people from my team and asked what would be the first thing that they would do if they got stuck with their application. Would you expect that everyone said they would press F1? I am sorry to disappoint you! Only one-third of the people gave this answer. The only solace is that none of them are technical writers!

The results make you think. How much time do we, as writers, spend on authoring and publishing Help? What do the translation costs amount to? Do we need to analyze our traditional Help architecture? If you thought of any of these questions, do not worry. There are answers to all of them.

To align ourselves with the upcoming trends in technology, we need to break away from our traditional Help systems and adopt the architecture of thin Help. These days, it is called Embedded User Assistance (Embedded UA).

What is Embedded UA?

The obvious question is: Does this mean that we are on the verge of discarding Help? The answer is a combination of yes and no.

Elements of Embedded UA

The following subtopics explain the most common Embedded UA components that you can include in your application.

Tooltips

A tooltip is visible when you move your pointer on a user interface (UI) element such as icon or a text box. You can also provide tooltips to provide full forms of acronyms that you have included on your UI page. Tooltip content should be short and precise.

Help Pop-ups

A Help pop-up can contain more detailed information than a tooltip. Only fields or sections of the application window for which users would need an explanation might need a pop-up. For example, commonly used fields such as Name and Description do not need a pop-up. However, for certain fields, users might need to understand how their input might impact the underlying process or further tasks. In this case, a pop-up might help users enter the most appropriate input.


Figure 1: Example of Help Pop-up

Help Areas or Help Trays

Depending on the complexity of the UI elements in the application window, one or more elements might need user assistance. In this case, including too many pop-ups might give a cluttered look. Here, using Help areas or trays is best. A designated area in the application area can serve as the Help area, and its contents can change depending on the control of the UI element. It is advisable to identify the usage of Help areas during the prototype phase. As a result, developers do not have to rework the screen layouts during their core development.


Figure 2: Example of Help Area

Labels, Hints, and Instructional Text

UI labels, inline text, below-field text, or instructional text are all examples of static text. It is recommended that you should comply with your style guide when you generate the Help text.

Figure 3: Example of Below-field Hint

System Messages

The error messages, information messages, and warnings that are displayed in the UI are examples of system messages. It is very important that the system messages are clear and helpful. In addition, make sure that you use consistent terms and phrases across all messages. Clear, meaningful, and unambiguous system messages can help users troubleshoot and resolve problems faster.

Best Practices for Embedded UA

A good embedded UA should satisfy the following aspects:

Just-in-time Information

The Embedded UA should address the information need of a user at the right time. Moreover, it should provide the authentic information that a user requires. The information that you provide should help the user proceed with further tasks. For example, in case of range-value fields, it would help if you provide the lower and upper limit values as hints. This would help users provide the correct input on the first attempt.

Obvious Location

Users should not need to hunt for Embedded UA. It should be available at a location that is obvious to the users. For example, you want to provide a pop-up for a set of fields in a screen. In this case, the Help icon should be available next to each field text box. Help icons in the right corner of the screen would not be helpful.

Brief and Focused Content

The information that you provide in the Embedded UA should be crisp and concise. In addition, it would help if you analyze the users of your application and provide the level of information accordingly.

Here is an example of how you can ensure crisp and concise content. The Help content that is mentioned below provides information about the elbow criterion threshold parameter.


Original Text
You set the elbow criterion threshold in order to specify the optimal number of clusters to be created in the clustering process.

The elbow criterion states that the number of clusters to be created should be such that adding another cluster does not provide any additional information. To understand this rule further, plot a graph of the percentage of variance that is explained by the clusters against the number of clusters. The graph indicates that the first few clusters add significant information. That is, these clusters explain a lot of variance. However, at a certain point, the marginal gain generated by adding new clusters will drop, producing an angle (an “elbow”) on the graph. To establish this angle (point), you need to define some threshold on the marginal gain. In other words, you need to define the elbow criterion threshold.


The value for the elbow criterion threshold can be in between 0.001 and 0.1. The default value is 0.01. If you increase the default value, you decrease the number of clusters that will be created. Conversely, if you decrease the default value, you increase the number of clusters that will be created. 

Revised Text
You set the elbow criterion threshold in order to specify the optimal number of clusters to be created in the clustering process. The value for the elbow criterion threshold can be between 0.001 and 0.1. The default value is 0.01. If you increase the default value, you decrease the number of clusters that will be created. Conversely, if you decrease the default value, you increase the number of clusters that will be created.
For details, see “Appendix 2: Clustering Parameters” in <Product Name>: User’s Guide.

In the revised text, only the text that is relevant to the user is retained in the pop-up. The rest of the content is included in the user’s guide.

Collaborative Effort

Working with Embedded UA should be a collaborative effort of usability experts, technical writers, and developers. In addition, it is advisable that you demonstrate the Embedded UA to all the involved parties, such as product management, development team, testing team, and technical support.
How to Implement Embedded UA
The content of Embedded UA can be in the form of property files. You would need to work with your developers to create a property file. There is absolutely no need to gear up a new Help tool or another content management system!

Traditional Help versus Embedded UA

Now that you have a little understanding about Embedded UA, let us see how we can differentiate it from our traditional Help. Here is a brief comparative analysis of traditional Help and Embedded UA.


Figure 4: Comparison between Traditional Help and Embedded UA

Conclusion

So having worked with Embedded UA, you can identify the complex scenarios of your application and include only these Help topics in your Help system. The user’s guide would be a comprehensive source of all the required information.

References

This article is compiled from information that is published in Help-on-Doc, the SAS intranet site.