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.


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


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.

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

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:

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


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:

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.