Technical writing/Structure

Levels of Detail

TWFred speaking on Levels of Detail (YouTube Video)

Structuring "Chunks" of Information

What is an information chunk?

An information "chunk" is a digestible unit of information.

When creating descriptions or instructions, a document structure will always be composed of a number of information chunks.

A telephone number, for example "555-3456", has two chunks, one of 3 digits and the other of 4 digits.

Chunks can also be known as "nodes" or "elements".

How do chunks work?

George Miller came up with the concept of the "magical number seven, plus or minus two". The idea that human brains can handle and store effectively around seven chunks of information at a time.

This means there are clear rules for presenting chunks of information. The rules apply to both printed and online information.

Structure and Function

Most things can be described in terms of structure and function – political systems, body organs, games, and systems.

Structure is Platonic in the sense that it approximates an ideal form. Function is Aristotelian in that it describes the uses we have for things. A Platonist might describe a horse as a beast with four legs, a tail, and a long back. An Aristotelian could describe the same horse as a beast for riding and even go a step further to give instructions for riding the beast.

Technical writers combine both philosophies in their everyday work. It’s just another thing that makes technical writing such an interesting profession.

Descriptions versus Instructions

Structures have Descriptions. Functions have Instructions.

For example, when describing a horse, list all the components that make up the horse. To identify the horse generically, define what a horse is in abstract terms. Give the audience enough required information to identify a horse.

When providing instructions for riding a horse, start with a description of the temperament of that horse, and how to use the saddle, reins, and stirrups the horse is wearing. Provide the audience with information required to take advantage of the horse's function...riding.

The Importance of Structure

Data without structure is not very useful. How do you find what you’re looking for? What’s important, and what is trivial? When you read about a subject, you expect some kind of organization that saves your time and effort in learning. If it is not organized, you will quickly give up.

Put the most important information first. What is most important? That depends on your audience analysis. Generally, warnings come first. Most introductions are a waste of time for the technical reader. They don’t read from start to finish, but rather search for a particular chunk of information.

So your index, table of contents, or other navigational aid should come first. Assume your reader is intelligent enough to find their way if your organization is clear and consistent.

Hierarchical Structures

Ideally, you know your audience so well you can rank the importance of your information. At any rate, you should make an intelligent guess at what should come first. This creates a natural hierarchy, where features are listed from most to least important.

If you follow the structure of the software or system you are documenting, you may choose to look at the user interface. For each unique screen simply go from the top left to the bottom right, listing each menu item, command button, or text box in order.

Hierarchies become obvious while analyzing the structure and function of your application, based on the primary uses of the system in the hands of your customers.

Horizontal Structures

More often, because of the nature of modern software and user interface design improvements, you’ll find that the application you write about has a horizontal or process oriented layout. This can be represented as a wheel just as well as a flat line.

Horizontal organization emphasizes the dependencies within the process. One thing follows another. At the same time, it shows that you may start the process at a variety of points. Anything can be first. There are many ways to achieve the users' goals.

Vertical Structures

Vertical structures, where there is only one path to follow, are rare. A single information chunk in the form of an instruction may be presented as a vertical structure.

Linear structures

A linear structure is familiar to everyone who reads books. There is a beginning, middle, and an end.

For something to happen, something must happen first. It depends, or has a “dependency” on the first action.

Non-linear structures

Online structures, as you quickly learn by surfing the internet, are non-linear. This means that there is no need for dependency. You can go direct from the middle to the end, and back to the beginning.

You can also provide navigation through graphical interfaces, as in this wiki example of an image map.

An image map allows you to identify an area in a graphic, so when the user clicks it a link opens. You can put many links in a single graphic.

Challenge to students

...look at the code under this illustration, it doesn't redirect because it's from media wiki instead of wikiversity...go to the instruction manual page to learn the details...go to the discussion and write why it doesn't work, or better, fix it and then describe the problem and the solution too...

picture of a foo

There is an instruction manual page about image maps at this wiki.

(Thanks to JWSchmidt)

Structural clash

Most systems have a mix of dependent and non-dependent functions. Where there are dependencies, a numbered hierarchical structure for the user information is obvious.

Where the functions are non-dependent, a non-linear or horizontal structure makes more sense.

But on paper, you cannot effectively represent a non-linear structure so you must arbitrarily assign importance to various features.

In each case, the key is good navigation designed with your audience in mind, with both structure and function. Allow your readers to search for the information they want with an online search function. Printed documents can have a table of contents and index.

Exercise 1

Re-structure this description of making scrambled eggs. For this exercise the audience is Sandra Jones.

How to make scrambled eggs for 2 people.

Assemble the following ingredients :

4 eggs
1/2 cup of milk
3 tablespoons of canola oil
salt and pepper

You will need the following utensils:

Medium size nonstick surface frying pan
A wide spatula
Mixing bowl, and whisk

Directions:

Break the eggs into the mixing bowl, add the milk, salt and pepper
Whisk all ingredients together until uniformly mixed, and until the mixture has a slight froth.
Pour the oil into the frying pan over a medium heat
Tilt the frying pan to coat the cooking surface of the pan with oil.
Let the oil heat up about 40 seconds to 1 minute and then pour the mixture into the pan.
The eggs will begin to cook and take on a more solid texture.

Use the method of flipping the egg mixture with the spatula once as it cooks for a more firm texture. Alternatively use the spatula to lightly scrape the eggs gently as the mixture firms for a softer texture. Place the scrambled eggs on a warm plate and enjoy ! Tasty accompaniments include bacon, ham, tabasco on the eggs and toast with your favorite jam.