Home > Articles > Software Development & Management > Object Technology

  • Print
  • + Share This
From the author of

Structured Writing

Structured writing is a technique invented in 1965 by Robert E. Horn, a psychologist at Columbia University. The idea behind structured writing is to organize written information in a way that makes it as easy to understand as possible. Although you might not have heard the term before, you will certainly have come across elements of it in corporate communications, on which it has had a big influence.

In structured writing, your goals are to do the following:

  • Structure pieces of information into easy-to-assimilate chunks called blocks
  • Understand the different types of blocks
  • Present each block in the optimal way to make it easy to access for your readers

In structured writing, a document is organized into the following:

  • Pieces of information. They can be sentences, formulas or figures. Each piece of information should be clearly expressed as simply as possible. It can take some time and work to achieve this!
  • Blocks. A block is just a chunk of information comprising about nine pieces of information organized around a single topic. Each block has a title to set its focus and make it easy to find. Typically, a block is a subsection in a document.
  • Maps. A map is about nine blocks. Each map also has a heading to define its focus and make it easy to identify. Maps are often sections or chapters in documents.

One of the key ideas in structured writing is that maps and blocks are considered to be reusable and can be combined in different ways to create documents suitable for different purposes. This implies that maps and blocks must, at least to some degree, be able to stand alone. Sadly, there is no commonly used word processor that has tools to explicitly support this kind of reuse!

There are two ways you can use structured writing in OOAD:

  • To present information. Whenever you need to write something for the stakeholders or other project members, you can use structured writing to improve your writing.
  • To capture information. Suppose that a long, windy, poorly written document lands on your desk. You can either spend time puzzling over it each time you need to extract some information from it or you can summarize it using structured writing to highlight the key points. Using structured writing you can often get a poorly written document down to one-tenth of its original size(!) and make the key information readily available at a glance.

Principles

Structured writing has several principles that are designed to make information easy to access, understand, and remember. Different authors describe slightly different sets of principles, and we use the following eight principles [Arlow 1]:

  • Relevance.
    • Include only information relevant to the topic.
    • Filter out irrelevant information.
  • Purpose.
    • What are the audiences for the document?
    • What should they get out of the document?
    • What do you want them to do with the information?
    • How much of the document are they supposed to read?
    • Can you ensure that different audiences can easily identify and access only those parts relevant to them?
    • What is your purpose in communicating? What are you trying to do?
      • Inform—impart useful information.
      • Persuade—convince them of a particular point of view.
      • Move—cause them to act in some way.
      • Guide—show them how to perform a particular activity.
  • Chunking—chunk information into small, easy-to-understand units.
    • Short sentences with a simple structure.
    • Simple diagrams.
    • Short paragraphs with a simple structure.
    • Try to keep to one topic per paragraph.
    • Present information according to its type (see next section)
  • Hierarchy—organize chunks into a hierarchy of meaning.
    • Large chunks contain smaller chunks with a finer level of detail.
  • Labeling—each chunk of information is given a descriptive title that clearly indicates its meaning.
  • Consistency—be consistent in the following:
    • Structure—titles, headings, subheadings, etc.
    • Presentation—layout, fonts, etc.
    • Terminology—your Project Glossary will help with this (see later)!
  • Integrated graphics—use graphics embedded in the text to enhance its meaning.
    • Never separate graphics into a separate section of the document.
  • Accessible detail—enable readers to read to different levels of detail.
    • Use chunking and labeling to separate and highlight the main points from the supporting points.

Of course, you could argue that all the above is just common sense. However, few corporate documents and analysis documents meet all these criteria.

Information Types

In structured writing you categorize information into seven types, and each type has a preferred method of presentation. These types are listed in the following table (and described in more detail in Secrets of Analysis).

Information Type

Semantics

Presentation

Procedure

Instructions for doing something

Action tables—concise, declarative, sequentially numbered instructions with one instruction per line. Each instruction begins with an action word. A use case specification is an example of an action table.

Process description

Explanations of how something is done

Action tables.

Diagrams to map the process (e.g., activity diagrams).

Structure

What a thing consists of

Diagrams to show the relationship of the parts.

Concept

A general idea derived from specific instances

One or more concrete examples.

The basis of the conceptualization.

Principle

Rules about something

Text (possibly highlighted with some typographical convention).

Fact

Objective information about something

Text.

Classification

Types of things

Text and diagrams to indicate the relationship of the classes and instances.

When you have a sequence of concepts, principles, or facts to present, consider using a bulleted list to do this:

  • Highlight the information
  • Keep related information together
  • Make information easy to access
  • Increase comprehension

Compare the previous structured text with the following unstructured version:

A sequence of concepts, principles or facts may be presented as a bulleted list, which has the advantages of highlighting the information and keeping related information together while also making it easy to access the information and increasing comprehension of the information.

I know what I prefer!

  • + Share This
  • 🔖 Save To Your Account