Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
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!