Best Practices: Do It Now!

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

Publishing Synopsis

I won a runner-up certificate of recognition for this article in the STC India Chapter 2014 Annual Competition. 

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

Foreword

Last night, my eight-year old daughter asked me for a word that she could quiz to her class. I instinctively suggested her this one:

Funambulism (also called tightrope walking) is an art of walking along a thin wire or rope, usually at a great height. One or more artists perform it in front of an audience.

Source: Wikipedia

She was very happy with my suggestion and dozed off peacefully. It was a clear indication that the matter was closed with her. However, it was still wide open in my mind. It kept me wondering to myself, “What made me suggest her this peculiar word? I do not recollect reading or hearing about it recently!” After a little brainstorming, the only analogy that I could think of is, “Isn’t this feat similar to what we do as technical writers, almost every day?” Well, I admit that I could be exaggerating. But, let us face it. In the pursuit of balancing between exceeding our performance and interacting with the ever-busy experts, we indeed are no better than acrobats.
I should thank my daughter for asking me for that little help. That night, probing my thoughts deeper, I had a self-realization. In the recent years, this tightrope journey has become a little smooth (not as smooth as a cake walk though) for me. Definitely not because I am ageing off! But, certainly because of the best practices that I have been implementing and improvising day-by-day.
You are not convinced yet with my self-realized thoughts? Then, let me take the liberty to share with you the seven best practices that I have permanently registered in my mind during my journey as a technical writer. I have been practicing them religiously and since then I do not remember losing out on anything. If you follow them, your journey too is bound to be more exciting. Perhaps, someday you might also agree that technical writing is not a tightrope walking altogether but at least a ropeway journey then!

 

An Acrostic Poem for My Best Practices

My poetic mind resonates the acrostic poem, DO IT NOW for the seven best practices that I follow for my documentation projects:

Figure 1: The Seven Best Practices

I am summarizing each of these best practices as my advisory words. You can tweak them according to the role that you play at your organization. 

Document Personas

The top-most best practice that determines your skill as a technical writer is how well you know your audience. Develop your understanding about the users who refer to your documents. This analysis is called personas definitions. It is surely not an easy task. But, collaborate with your team members who are in involved in the implementation of your product or who are directly interfacing with the users. They could be people working as technical support, marketing experts, product managers, or onsite developers. When you know our audience well, you never write more nor write less. All you do is write the right. And yes, this best practice is the premise for implementing the principles of minimalist writing—the latest buzzword in technical writing.

Figure 2: Sample Personas

  

Organize Your Documentation Set

Identify the scope of your documentation project. Accordingly, delve into your list of documentation deliverables and finalize it with the stakeholders. It is very important to know the sequence in which one has to use the documentation. So, you could use this list to create a progressive documentation plan. 

Figure 3: Sample Documentation Set

Identify Roles and Responsibilities

Map the personas with your documentation deliverables and for each persona define the major roles and responsibilities. Are you noticing that your third best practice is shaping into a documentation map? A handy documentation map can help a novice user navigate easily through your documentation set. Moreover, it helps you get a fairly good idea about how much work you have at hand, especially if you are the sole writer on the project. Also, this broad classification helps you develop the table of contents and gives you an at-a-glance view of your documentation project. 

 

Figure 4: A Sample Documentation Map

Trigger Agile Documentation Methodologies

Give it your best shot to adopt and implement agile documentation strategies. Synchronize with your developers and testers and make sure that you complete the triad. Be a part of the story-point discussion and chip in your thoughts about the documentation impact. Make them understand that it is a three-legged race and not just two! The agile methodology helps you progress along with the rest of the team and does not keep you staggering till the end.

Nurture Complete Information

Strive hard to procure complete information from the subject matter experts. Participate in their discussions. Do not hesitate to raise your queries and sort them out as soon as possible. When you have the end-to-end information, you can decide about what is important and what is not. This practice can help you augment your profile as a domain expert.

Own Your Content

Now that you have the complete information, you can begin with content generation. But, remember it is not your exam paper that evaluates how much you know. So, be your own advocate and write only that is required. Also, leave some room for exploration. By practicing thoughtful writing, you can be the content owner.

Win Over With Your Words

Each time you generate content, review it word-by-word as if it has no time for another review. A thorough self-review reduces the rounds of technical, editorial, and peer reviews. Be confident that no one knows the content as best as you do. Use the magic of your words and win over your audience! 

Conclusion and References

The seven best practices that I have summarized in this article are based on the standards and processes that are set up at my organization for user documentation. However, this article reflects my original thoughts about these best practices and the benefits of implementing them. I hope these best practices are equally useful to you and help you succeed as a technical writer. So, what are you waiting for? Do it now!

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.