Technical writing/Structuring Information EE

• back to Technical Writing Level 1

Structure and Function?

Structure describes how a thing is built (the architecture).

Function describes what a thing does.

We can describe the structure and functions of everything

Figure 1-1 A Kettle

• This kettle is made out of metal (structure)
• This kettle boils water (function)

A computer program also has a structure and functions

Structures require Descriptions

Give your reader the information required to identify a bicycle.

To describe the structure of a bicycle:

Define what a bicycle is in general terms

• List all the major parts of the bicycle
• Describe how the parts are attached
• Describe how the parts relate to one another

Functions require Instructions

To give someone instructions for riding a bicycle:

• First warn of any hazards and possible dangers
  • Crashing
  • Loss of balance
  • Falling over
• Instruct how to mount the bicycle
• Explain the function of the saddle
• Instruct how the brakes work
• Give your reader the information required to ride the bicycle

How does the reader find the information they need?

Structure

The most important information must be first.

Find out what information is most important to your reader and then put that information first.

Then the reader will always quickly find needed information.

The information without structure is not useful.

The reader must understand how the document is structured.

If the document is part of a set of documents all of the documents must have the same structure.

The order in which the concepts are introduced.

What order must the information be in?

The order that the information is presented is important.

Warnings must come first because they keep the reader safe.

For example:

“WARNING: Do not attempt to smooth out your facial wrinkles with this steam iron.”

Next write a scope that clearly defines what the document:

• Contains
• What product including software release that information relates to

For example:

“This document describes the Lemon group of products. For the configuration tables please see Lemon Configuration Tables.pdf”

Readers look for a specific piece of information when they read a document.

Provide your reader with:

• An Index
• A Table of contents
• cross references (For Web based content)

Assume your reader is intelligent enough to find their way if your organization is clear and consistent.

Types of Structure

There are five types of structure possible. Three are listed here. These are:

• Hierarchical structures (used in Functional Specifications and feature

lists)

• Linear structures (read from start to finish like a novel)
• Non-linear structures

Hierarchical Structures

The Hierarchical Structure describes each screen of the user interface, from the top left to the bottom right, listing each menu item, command button, or text box in order. A hierarchical structure describes all the functionality that must be displayed, for example, in a specification. Content Management Systems can be arranged as a Hierarchical Structure.

End of Lesson Test

1. Why is it important to structure the document in a way that the reader understands? If you structure information in a way, that is not understandable for the reader, s/he won`t be able to find information that s/he needs and the documents will be unuseful.
2. What order must the information be in? Warnings should be first, next you need to tell what the document contains and what product the information refers to, an index, a table of contents and cross references should be the next.
3. What type of document is a hierarchical structure for? Functional Specifications and feature lists.