Technical writing structure
From Wikiversity
back to Technical Writing Level 1
[edit] Structuring "Chunks" of Information
[edit] What is an information chunk?
An information "chunk" is a small unit of information.
An information "chunk" can be as small as a number or as large as a chapter.
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".
[edit] How do chunks work?
[edit] Structure and Function
We can describe the structure and functions of most things. A computer program has a structure and functions.
[edit] Excercise 1 Describe the structure of the table in front of you.
Use as few words as possible. Ask yourself these questions:
- What materials is the table made from?
- Are these the only materials that it is possible to build a table from?
- What is its geometry (Shape of individual parts)?
- What are the dimensions of its overall height width and depth?
- Draw a picture of the table?
- How are the individual pieces (component parts) joined together?
- Is it an active or a passive object (does it do anything)?
[edit] Excercise 2 Describe the functions of the table in front of you
Ask yourself these questions:
- How many things can the table do? (write a list)
- Is the table specially adapted for a single purpose?
[edit] How do you find what you’re looking for?
Data without structure is not useful.
[edit] What is information important, and what information is trivial?
Find out what information is most important to your reader and then put the most important information first.
[edit] What is most important?
Most introductions are a waste of time for the technical reader. When they read the document they are looking for a specific piece 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.
[edit] Hierarchical Structures
Find information about how your reader needs to use your document. The project or product manager should know this. If the project or product manager does not know, guess what should come first and then get your reader to validate whether you were correct. This creates a natural hierarchy from most to least important.
[edit] 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.
[edit] 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.
[edit] Linear structures
A linear structure is familiar to everyone who reads books. There is a beginning, a middle, and an end.
For something to happen, something must happen first. It depends, or has a “dependency” on the first action.
[edit] 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.
[edit] 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...
There is an instruction manual page about image maps at this wiki.
(Thanks to JWSchmidt)
[edit] 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.
[edit] Exercise 1
Re-structure this description of making scrambled eggs, for this exercise the audience is Sandra Jones.
Scrambled eggs for 2 people.
You will need the following ingredients and utensils : 4 eggs, 1/2 cup of milk, 3 tablespoons of canola oil, salt and pepper, medium size nonstick surface frying pan, a wide spatula, a mixing bowl and whisk.
Break the eggs into the mixing bowl, add the milk, salt and pepper. Whisk all ingredients together until uniformly mixed and mixture has a slight froth. Pour the oil into the frying pan over a medium heat. Tilt the frying pan to spread the bottom 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. Also you could use the spatula to lightly scrape the eggs gently as the mixtures 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.
[edit] Further Reading
- The Magical Number Seven, Plus or Minus Two
- George Miller
- Chunking
- Technical Writing and XML
- Structuring Information
- Writing Instructions
- How to write instructions
- Effective Technical Descriptions
- Writing Descriptions
back to Technical Writing Level 1
How to edit Wiki
