10 Minimalist Principles for Good Technical Writing

Principle Six: Organize Information Logically

Principle Six: Organize Information Logically

Unstructured text typically consists of one paragraph after another, maybe with a randomly formulated title here and there. Information presented in this way is monotonous and visually unappealing. Furthermore, unstructured text provides no anchor points for the human eye nor perceptible patterns which makes it difficult for users to skim and pick out pertinent information.

Example of unstructured text
Unstructured text

The characteristics of structured text include patterns and repetition. In technical writing, the systematic use of logical conventions helps users to absorb information more easily and to apply what they have learned.

Example of structured text
Structured text

Topic-based approach

“Information mapping is a research-based method for writing clear and user focused information”

In technical writing, information mapping is an approach to developing information based on users’ needs and the purpose of the information. Information is classified by type and is then organized and presented in logical units. This approach, also known as structured authoring or topic-based authoring, promotes simplicity and consistency. In technical writing, a topic could be a chapter, a subchapter or a web page that focuses on a specific artifact, concept, process, or task.

Horn’s information types

Robert E. Horn‘s theory of information types from the 1960s is still a useful reference for classifying information in technical and business communications at topic level. Horn proposes six types of information. The following definitions of and examples for each information type give a general impression of how information can be classified and are loosely based on Horn’s work.

  • Procedure: A set of steps a user performs to accomplish a task, for example, a step-by-step description of how to make, resize, and save a screenshot.
  • Process: A sequence of events and activities that result in a specific outcome, for example, the steps involved in setting up a new online shop hosted on an online platform, from setting up an account to customizing the shop design and layout through to importing product and inventory data and optimizing the shop performance before the shop goes live.
  • Principle: A statement that explains the underlying design, workings, or rules of something, for example, a description of a subscription-based online service for storing and sharing digital images.
  • Concept: A group of things that share a critical set of attributes, for example, a description of the coding, design elements, and testing approaches used in responsive web design.
  • Structure: A textual description or visual representation of an entity that has parts, for example, a database that stores product data that can be used by multiple applications.
  • Fact: An objective and neutral statement, for example, a description of a product and its attributes or a set of ingredients and equipment required for making a pizza.
Guidelines and subject matter expertise

In longer forms of technical communications that are designed only or also for print, such as guides, user manuals, or product specifications, the idea is that each topic of a particular type follows the same structure and layout. So far so good; however, the task of classifying information is often not clear-cut. The concept of structured authoring is easily understood, yet it is not easy to apply nor enforce over large volumes of information that multiple writers are developing or updating. Topic-based authoring takes planning and time.

To follow a topic-based approach, guidelines need to be in place. Without a systematic approach to classifying, splicing, and structuring information, even if it seems that content production is faster, the quality of the output invariably suffers. Furthermore, structured text is typically easier to translate, update, and reuse; whereas unstructured text frequently requires extensive rework to optimize it for processing during subsequent phases in the content lifecycle.

From chaos to order

Technical writing that neglects the principles of good information design can result in confusing and distracting information. The purpose of writing is communication, not words for the sake of words. When users are confronted with text that lacks any sense of order, it is difficult for them to find the information they are looking for. Imagine a grocery store that puts a shower gel on the same display as the fruit because the shower gel has an apple fragrance. An apple is a fruit, but the fragrance of the shower gel is not the attribute by which it is classified. In a similar way, a user is looking for information about how to make, resize, and save a screenshot does not expect to first have to wade through a lengthy description of a hosted service for storing images.

Topic layout

To ensure that each topic of a particular information type follows the same layout, a few simple rules can be applied. The title of a topic should indicate the information type. For example, if a topic describes a procedure, you might call your topic “How to make a screenshot”. If you then create another topic that describes step-by-step how to resize a screenshot then the logical and grammatically consistent title would be “How to resize a screenshot” and not, for example, “Resizing screenshots”. Likewise, for all further procedure topics that you create, the title of these topics would also begin with “How to…”. In the same way, you would then define and stick to a convention for the titles of concept topics and all other information types that you require.

Consistent grammatical forms

Topics themselves can also be broken up into sections with headings that identify the information that the sections contain. It is important to send out similar messages consistently by using the same grammatical form for equal or similar ideas: at topic level, at section level, at sentence level, and even down to the level of as short phrase, for example, an item in a bulleted list (see also Principle Two: Use Parallelism).

Bulleted lists are in themselves a form of punctuation and a great way to shorten text. A group of items in a list, each item with its own bullet, signalizes “We belong together!”, for example, for list of product features or benefits. In the same way, a group of items in a numbered list indicates “We belong in this order!”, for example, for a list of steps that a users needs to perform as part of a procedure or a process description. Titles and section headings, bulleted and numbered lists, tables and charts, notes and cautions, and font sizes and colors are just some of the formatting devices you can use to break up the monotony of pure prose and punctuate the information you want to convey to users. Principle Eight: Aid Navigation will also look at how text formatting helps users navigate through content.

Communication is the purpose of writing.

The purpose of writing is communication, not information for the sake of information. Attention to words, sentences, grammar, and punctuation is important in technical writing; however, it is the way different units of information are organized that determines whether or not writers communicate effectively to users. Ideally, user needs should structure the form of communication, or in other words, technical communication should always fulfill user needs.

Asking “Who?” and “Why?”

Horn’s information mapping is certainly a good starting point for an information design; however, the information types might need be modified or substituted for other types to accommodate broader and more modern forms of communication, for example, on web sites where the boundaries between marketing content and technical communication become blurred.

Tailoring information

In technical writing, it is not realistic to start structuring information in topics before asking the following questions: “Who are my target users?” and “What is the purpose of this information?”. Many complex scenarios in technology, business, and science comprise multiple concepts and processes, which in turn necessitate tasks to be performed by different user groups, for examples, business users vs. technical users or frequent users vs. occasional users. Before users perform a task, they need to understand the purpose of the task. A technical user who is responsible for keeping entire system landscape up and running will likely need more detailed information about the underlying concepts, structures, and principles; whereas a straightforward procedure is sufficient for a business user who just want to get the job done. The information provided for different user groups can be tailored accordingly.

Different users need to know different things.

Different users need to know different things. Therefore, writers need to be able to describe things from all user perspectives and to be able to discern what a user needs to know and what can be left out. Answering the questions“Who are my target users?” and “What is the purpose of this information?” can sometimes reveal that important information is missing or that certain information is redundant for the task at hand. To be able to organize and present information in a way that is most effective for users, understanding users and their needs is just as important as understanding the subject matter itself.

As a minimalist principle for technical writing, organizing information in logical units brings more attention to its purpose and makes it easier for users to find the information they are looking for. People are overwhelmed by information that is not organized and will generally seek some means of grouping or categorizing it themselves or will simply not read the information at all (we will cover this some more when we look at pattern recognition in Principle Seven: Communicate Visually). Therefore, classifying information with its underlying purpose in mind and presenting information with the needs of users in mind helps convey information more clearly and reduces the risk of information overload.

Next up:

Principle Seven: Communicate Visually

  1. Keep sentences simple
  2. Use parallelism
  3. Use active voice
  4. Choose verbs with care
  5. Negate with purpose
  6. Organize information logically
  7. Communicate visually
  8. Aid navigation
  9. Be consistent
  10. Focus on what is important

This article is part of a series of articles entitled 10 Minimalist Principles for Good Technical Writing.Broadly speaking, minimalism is any style or technique that is characterized by an extreme reduction to necessities and radical simplification. A minimalist is a person who strives to restrict the means and ends required to achieve a goal to a minimum. Applying minimalist principles to writing can support the key objective of technical communication: to enable users to learn and accomplish as much as possible, on their own, in as short a time as possible.

About Helen Fawcett:

In a nutshell, I optimize user interface text such as control labels and create on-screen instructions and help documentation for developers & customers. | Helen works as a user assistance lead at SAP SE.
More about me
Home Minimalist PrinciplesTechnical WritingWriting Style Principle Six: Organize Information Logically