Top Seven Guidelines for Minimalist Writing

Customer Feedback Is Valuable

As technical writers, we are always curious about how useful our documents are to our customers. We rarely miss an opportunity to seek feedback from our customers, whether internal or external. One such golden opportunity knocked at my desk when a bunch of new developers were assigned to our product. Instantly, I assured them that the user’s guide will help them get started with our product. Eventually, I interviewed them for their feedback. Their valuable feedback helped me restructure my guide and remove redundant information.

In retrospect, I thought it is worthwhile to document my findings as ready-to-use guidelines. I realized that the guidelines that I had compiled echoed the best practices for minimalist writing. These guidelines will help you implement minimalist writing without extensive rewriting and restructuring. You can use these guidelines in any order and in a manner that is appropriate for your documents.

An Overview of Minimalist Writing Approach

Step 1: Encompass Introduction into a Single Chapter

The first section of our documents typically contains a set of introductory chapters. In these chapters, we include detailed information about the product, user interface, and certain common tasks. There is ample scope to rework on these chapters.

Minimalist writing approach

·       Answer a simple question, “Do the users need all this information to get started with the product?”

·       Based on your answer, categorize your topics as Most significant, Significant, and Insignificant.

·       Remove the topics that fall into the Insignificant category. If this information is available on your product page, you can include this URL in your document.

·       Combine the Most significant and Significant topics into a single Getting Started chapter.

This guideline helps users perform their tasks right away rather than read through the detailed introduction. Otherwise, they might eventually lose interest in the document.

Step 2: Focus on Tasks First and Concepts Later

Before users start performing a task, we want to make sure that they know what they are heading for. In this linear-reading approach, we tend to include end-to-end conceptual information. This information can be important. However, users might not need it immediately to complete the task at hand.

Minimalist writing approach

·       Look for concept signifiers that you can move to the end of task, topic, section, or chapter. For example, these signifiers contain the following keywords: Overview, Introduction, Understanding, and How Does Something Work.

·       Restructure your document, so that the task-oriented topics are in the top order, followed by the conceptual topics.

·       Determine whether any of the conceptual topics can be a part of an appendix.

When you follow this guideline, you include just-enough conceptual information that the users need to accomplish their task.

Step 3: Eliminate Unnecessary Screenshots

We tend to include a screenshot for almost each step that a user performs. But, users might just ignore these screenshots because most of the time they might simultaneously be working with your product. Besides, unnecessary screenshots just add to the file size.

Minimalist writing approach

·       Include only those screenshots that give a result of a task.

·       Common tasks such as add, save, or delete information or menu navigation do not need any supporting screenshots.

·       If you are documenting a task that users perform by using a wizard, you can eliminate the screenshots.

When you insert screenshots sparingly, the page count reduces. As a result, users get a fairly good idea about how much content they have to read. 

Step 4: Do Not Document Industry Standard Buttons or Tasks

Most of the users are well-versed with the industry standard UI elements. So, you can remove information that they would certainly know.

Minimalist writing approach

Identify UI elements and common tasks that do not need any explanation. You can remove them from your documentation unless they result into an unexpected behavior. For example, here is a list of items that you do not need to document:

·       Menus

·       Buttons or icons such as Help

·       Common tasks such as open, save, and delete

·       Common login procedures

When you implement this guideline, your focus automatically shifts to documenting what users do not know rather than what they might know.

Step 5: Insert References for Explanatory Text

Too much of conceptual information in the middle of a task is often distracting. It might even confuse users and they might actually lose the flow of their current task.

Minimalist writing approach

Identify the bulky paragraphs that you might have included right in the middle of your numbered list. Include them in the conceptual information and provide a cross reference to it.

This guideline enables you to practice the concept of detail-on-demand. That is, provide more information only when it is requested for.

Step 6: Convert Narrative into Numbered or Bulleted Lists

Users refer to our documents when they cannot accomplish a particular step or a task. Therefore, we should help them locate the exact section that they are looking for. Moreover, reading becomes easier with short and precise information.

Minimalist writing approach

Look for transitional words such as First, Next, Then, and Finally. These words signify tasks. Trim these narrative paragraphs into a numbered list. Similarly, for parallel items, convert the information into a bulleted list.

This guideline helps you make your content task-oriented, structured, and concise. 

Step 7: Document Only One Method of Doing a Task

Often there are more than one methods by which you can do a particular task. For example, you can perform a task by choosing a menu option or clicking a toolbar icon.

Minimalist writing approach

If users can perform a task in more than one way, document the most common. You can remove the alternative methods or document them as common tasks.

This guideline encourages users to explore your product.

Conclusion

If you want to draw attention of your users to your documents, think like a minimalist. Here are a few basic thoughts that you should consider when you adopt minimalist writing:

·       Avoid the obvious.

·       Be assertive and avoid extensive passive and narrative prose.

·       Comprehend the product workflow and structure your document accordingly.

·       Discuss your strategy with stakeholders.

·       Evolve your document based on iterative reviews.

Publication Details

This article was article was published in the August 2015 edition of the Indus magazine.

The T-Shaped Technical Writer

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

Publishing Synopsis

I had published this article for the tcworld India 2015 conference contest. I was declared as the winner of the competition and got a free entry ticket for the conference. Here's a sneak preview of the announcement of the results.

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

Foreword

Yesterday evening I sent an important e-mail about my product documentation. As a normal practice, I navigated to my sent folder to ensure that the recipients list included all the stakeholders. The list was endless! In the span of just a few years, I realized that the recipients list had extended tremendously. I smiled at myself as I recollected my fresher days when I had e-mail exchanges only between my development team and fellow writers. Today, the emerging standards, and processes have amplified the interactions of technical writers with many other teams. Product documentation is more of a collaborative effort and the ‘I’ that connected me to the mainstream has changed into a ‘T’.
If you are pursuing technical writing since at least past five years, I am sure that you correlate to the metaphor that I just used to describe the change. Yes, indeed, we are T-shaped technical writers. Here is the Wikipedia definition that can probably convince you.

The T-Shaped Skills of a Technical Writer

Here is how I visualize the Wikipedia definition for my skills.

The Role Model of a T-Shaped Technical Writer

In my view, the T-shaped technical writer simultaneously serves a number of distinctive roles.

Trustworthy Team Player

Aspires the team goals, commits to the tasks at hand, and glorifies the team’s success.

Strong Communicator

Wins over the hearts, and rules over the minds through effective, accurate, and economical verbal and written communication.

Holistic Intellect  

Comprehends the complete information, analyzes it thoughtfully, and builds a powerful knowledge management system for all audiences.

Active Listener

Lends an attentive ear to capture information, and disseminates it creatively through suitable channels.

Passionate Leader

Collaborates at diverse levels with cross-functional professionals, and designs and monitors the documentation plan.

Enthusiastic Innovator

Looks forward to learn and adapt to new trends and technologies, develops new ideas, and evolves best practices.

Dedicated Mentor

Facilitates as a friend, philosopher, or guide and empowers fellow writers to win over in difficult times.

Conclusion

I am convinced that I am a ‘T’. Are you still dabbling into the calligraphy of an ‘I’ or a ‘T’? If so, then it is high time that you bridge the gap. No matter what you are doing, you need to think broadly and deeply.

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.