mkaz.blog

Notes on Technical Writing

Over the past year, I've worked off and on documentation for WordPress. I started contributing during a launch freeze to help developers transition to the new block editor. I found I enjoy writing documentation, it is rewarding to craft quality documentation that helps people.

Over time, I've read numerous resources on technical writing and documentation. I've collected together my notes both to help me remember key points later, but also as a tool to help me think about writing now.

Principles

The following principles I try to keep in mind when writing documentation.

  • The purpose of technical writing is to help users accomplish tasks as quickly and effectively as possible. [#]
  • People learn by doing, prefer to be shown and not told.
  • Get users to their first success quickly.
  • There is more than one type of documentation.
  • Keep it simple, write in plain language

Tips

  • Know your audience, know your purpose
  • Put the most important information first
  • Use bullet lists
  • One idea per paragraph
  • Edit, Edit, Edit

Avoid Meta Writing

Avoid writing about the writing, try to keep the active parties as the writer and the reader.

You don't need to tell the reader what you're going to tell them. Just tell them.

  • Bad: This chapter discusses the factors that cause names to rise and fall in popularity.
  • Good: What makes a name rise and fall in popularity?

Don't refer to sections or paragraphs in the writing.

  • Bad: Summarizing the preceding section about…
  • Good: In summary, …

Don't tell the reader something is extremely complex; likewise don't tell the reader something is simple. The reader will make up their own mind about a concept being easy or hard.

An exception, you do want state any assumptions, for example around skill level. For example, this tutorial assumes previous programming experience.

Minimalist Instruction

John M. Carroll and his colleagues at IBM studied creating support documents analyzing the best way to get a user proficient. In the 1980s, they developed a minimalist approach and created a wonderful Operator Training Manual for the IBM Displaywriter, imagine having to introduce someone to using a word processor for the first time.

The four principals of minimalist instruction:

  • Choose an action-oriented approach. Users typically want to do things. This principle reflects the user-centric nature of minimalism.
  • Anchor the tool in the task domain. A tool is a means to an end. This principle asks designers to select training tasks that are meaningful for the user.
  • Support error recognition and recovery. To err is human. There are several ways to increase user competence and comfort levels in handling mistakes.
  • Support reading to do, study and locate. Designs must fit as much as possible the diverging needs and propensities of the intended audience. This principle reflects the user-centric nature of minimalism.

Read deeper about Minimalist Instruction from the Department of Instructional Technology at University of Twente, Netherlands.

Constructivism

American psychologist Jerome Bruner studied human cognitive psychology. A major theme in Bruner's work is that learning is an active process in which learners construct new ideas based upon their own knowledge. Applying the principles of constructivism to documentation:

  • Try to encourage readers to discover principles by themselves
  • Translate information into a format appropriate to the reader’s current level
  • Organize material in a spiral, so it continually builds upon what they have already learned.
  • Engage in an active dialog, invite users to act "Please try", "See what happens", "Explore yourself"

Read more in my follow post Enable Learning in Technical Writing

Types of Documentation

Daniele Procida wrote What nobody tells you about documentation that discusses there isn't just one thing called documentation, but there (at least) four types of documentation.

  1. Tutorials - A tutorial is learning-oriented for newcomers, a directed set of lessons to give the user basic confidence and skills. A tutorial should not assume knowledge or language, but is there to take a beginner who doesn't know what questions to ask through learning.
  2. How-to Guides - A how-to guide, or FAQ is goal-oriented, directed by the user. A how-to guide can assume the user has basic knowledge and language, but needs to know how to solve a specific problem.
  3. Explanation - An explanation or overview document is understanding-oriented providing background or additional detailed context.
  4. Reference Guides - A reference guide is information-oriented, it is accurate and complete describing the machinery. API documentation is an example of a reference guide.

Resources