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.
