writing tips and tricks

Your content is not clear unless your users can:

• Find what they need
• Understand what they find
• Use what they find to meet their needs

High-quality user documentation can:

• Ensure the effective and systematic operation of the product.

• Support user learning and reduce user support costs.

• Increase brand reputation and loyalty.

Conversely, poor-quality user documentation can:

• Frustrate or confuse users.

• Cause user dissatisfaction.

• Reduce user trust in the documentation, possibly to the extent that they bypass important instructions.

Minimalism

Based on the research of John M. Carroll at IBM’s Watson Research Center, minimalism is text-based learning that encourages exploration of technology rather than rote learning. To apply minimalism to writing, use fewer words in action-oriented text. Cut back on descriptions. Eschew useless information. Useful information shows rather than tells, and allows a reader to act. It eliminates ROT – the redundant, outdated, and trivial.

JoAnn Hackos’ Four Principles of Minimalism are helpful and useful. They are:

• Principle One: Focus on an action-oriented approach

• Principle Two: Ensure you understand the users’ world

• Principle Three: Recognize the importance of troubleshooting information

• Principle Four: Ensure that users can find the information they need

Results of minimalism, when applied to technical writing

• Understanding of the user's journey

• Usable

• Minimal

• Appropriate

• Findable

Four minimalist writing principles

1. Choose an action-oriented approach. Emphasize tasks before you explain concepts and ensure that tasks follow a real workflow.

2. Focus on users’ real goals. Anchor everything that you write in the task domain rather than the tool domain. For example, do not lead with tabs or menu items (“the Home tab enables you to change fonts”); lead with what you can do through them (“Change fonts through the Home tab”).

3. Support error recognition and recovery. Provide steps to recover from mistakes whenever errors are likely to occur, and provide carefully labeled troubleshooting steps within procedures.

4. Support information access. Readers view technical content as a series of answers to questions that they have about the product. Craft your headings, labels, and topic sentences accordingly.

One of the most valuable changes you can make to your content is applying minimalism. Take the opportunity to learn how to apply minimalism to your content. It not only improves your content, but it also makes your users happier and less frustrated (leading to customer satisfaction improvements). It also allows you to further define and refine your entire content strategy.

Topic-based writing

What is topic-based writing? It's a way of writing that is focused on a single topic.

The three basic topic types are:

• Task topics: The should provide information to help users accomplish a task. Describe the benefits of the task or the purpose of the task, or both. Remember, we're writing this so that this task topic can stand on its own. Include information that will help users understand when the task is and why it's necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for Task A. In some cases, add more information about why the task is beneficial. Put yourself in the user's shoes; what's the reason for coming to this topic.

• Concept topics: Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?" If the concept is unfamiliar, you can start with a brief definition. Avoid turning the concept topic into a task.

  Remember, this is a "conceptual" or "informational" topic. This is the type of topic a user might reference first to understand the product better before using it or even buying it. In this topic, you'd write about how a feature works. For example, if you wanted to explain how external user authentication works in the product, this is the topic type to use. In this example, you'd keep the content focused on "how external user authentication works in the product." You're not explaining the high-level concept of how external user authentication works; you're explaining how it works in the product. Big difference, especially for the user journey.

• Reference topics: A reference topic is not required but can be a useful format for a long table or a list of documents for further reading. It's a relatively flexible topic type, in my opinion, because I think of this topic type as the old school "Appendix" at the end of a guide. Nonetheless, this topic is relatively short because we're keeping it focused on a single subject.

Scenario and goal-based writing

--TBD--

Bullet lists

A bulleted list, also called an unordered list, is a vertical list of items when order is not important. Use bulleted lists when you want to present information that is easily scanned by the reader.

Appropriate use of bullet lists

Follow these guidelines when you write bulleted lists:

• If you have four one-word items or less, include them in a paragraph; however, if you want the items to stand out, put them in a list.

• Use a bulleted list when you have a list of two or more items when any of the items have two words or more.

  If you have one item, a bullet isn't necessary because one item doesn't make a list.

• Make sure that the items in a bulleted list use a parallel structure and have the same value.

• If you want to separate two or more bulleted items with the word and or or, place the word in italic on a separate line at the same level of indentation as the bulleted text.

Conciseness

Using precise language helps readers to retain information more easily. Long dense sentences with a lot of information are difficult for the reader to parse. Such sentences are also difficult to translate.

• Write in a clear, straightforward style.

• Use single and simple words. Unnecessarily complicated information forces readers to work harder to comprehend a concept.

  INCORRECT
  Utilize a manually powered fastener-driving impact device.

  CORRECT
  Use a hammer.

• Cut out unnecessary words. Strive for conciseness by eliminating any word that is not crucial to the sentence.

  INCORRECT
  Install the drive module in conjunction with the array module.
  In order to configure the software, a planning checklist is required.

  CORRECT
  Install the drive module with the array module.
  To configure the software, you need a planning checklist.

• Use concrete nouns. If words are inaccurate or difficult to understand, the reader must either apply extra mental effort to substitute the correct word or “learn” incorrectly.

  INCORRECT
  These aspects are important considerations for usability.

  CORRECT
  The physical components of the command module are important to its usability.

Definitions of Informational Notices

• CAUTION Indicates a potentially hazardous situation that could result in data loss (or other interruption) or equipment damage.

• IMPORTANT Indicates information or criteria that is necessary to perform a procedure correctly.

• NOTE Indicates a clarification of a concept or presents a maintenance tip.s