paper work

The process and instruction patterns are similar and different, so they are covered together in these lecture notes.

Process documents tells you why things are the way they are, like a textbook, a reference book, a user’s guide, or a tutorial.

Instructions give you stepbystep instructions or howto commands to perform a specific task.

A summary of the process versus instruction patterns is given in Table 1.

As an author that must provide information to people as part of your job, you need to decide how to organize that information.

You would be cued to use the process pattern by someone using any of these words:

· conventions

· procedure

· process

· reference

· standard operating procedures or SOP

· standards

· user’s guide

You would be cued to write instructions by someone using any of these words:

how do I …?

Various questions/tasks need to be completed during the prewriting process for either pattern.

Identify the purpose; explain that in the first section. What is going to be covered and why? When this section is long (more than one short paragraph), create a heading for it, just don’t call it Introduction.

Who needs this content? What do they need to do to complete their task/job?

What can you assume about the reader’s knowledge of the topics? You want to analyze any assumptions you can make about the reader’s ability to understand the content so that you can know writer using the appropriate terminology and reading level.

Brainstorm the content (e.g., use a mind map).

When you read a textbook, you understand the information as you go along because its order of information builds your understanding. When you have a large topic of information that you need to order into progressive level of disclosure, how do you go about it?

The biggest challenge with creating a process outline is that in most cases, you are writing about content that you’d forgotten you knew. You were using the information, but don’t remember all the details of it.

For example, I’ll assume that you know how to drive. Do you remember all the rules of driving on the road that you read in your driver’s education book? No. However, once you’re in the car and driving along, you automatically (unconsciously) do what you had originally been told to do, like drive on the righthand side of the road, use turn signals, and look before moving into another lane. Those rules you learned came with why explanations (i.e., why things are the way they are or process), but now that you automatically do them, you may remember just the rule and may have to think about the why again, (or maybe you even unconsciously do the rule without thinking about it). However, you still drive with that why understanding embedded in your actions.

So, the challenge in process writing is to reremember all those rules and why things are done that way so that you can write them down for the next person who needs to learn them.

Mind map – for process documents, the best place to start is with a mind map.

Map out all the possible ideas of topics that you need to cover or relate to your topic. These might be the standards or conventions or best practices for this topic, or maybe the standard operating procedures, or even the process. As you brainstorm, identify links between the ideas to help you see connections.

Remember that with all your brainstorming, you’ll be adding rules to these concepts (which are the why things are). Avoid brainstorming about:

situations where there’s no rule, that might not be an avenue to brainstorm about.

benefits, advantages, or why questions about the topic; these ideas move your thinking into persuasion. Persuasion is a different pattern; for this one, you want to remember that why things are is not the same as why do it.

Avoid brainstorming about history, definitions, or what the topic means in general. In this case, these ideas would move your thinking into the realm of research writing. Process is not a research paper.

Order your mind map into levels.

With your mind map completed, look at each element and ask yourself, “What is the first piece of information the reader needs to know before all others?” Put a 1 next to that idea. Then ask yourself, “What is the next piece of information that would follow that idea?” Put a 2 next to that idea. Keep following this question and numbering until all elements in the mind map that need to be covered are accounted for. That listing turns into your outline or table of contents.

As you examine the ideas from your brainstorming output, avoid putting the same idea under multiple different headings. Remember, headings give the reader a clear understanding of the content of the section, so they can skip a section when they know its content. If that concept is spread out under various headings, then the headings couldn’t be very clear and it’s not clear to the reader if they want to skim/skip sections.

Examine your outline (or TOC) for potential problems.

See if your outline has good PLD – remember that topics build on one another. Some tests to perform include looking at:

topic grouping

When you have lots of ideas that can be grouped together under another topic, use that broader topic as a heading, and use the smaller ideas as a subheadings.

topic order

check to see if you’re examining them in the right order

For example, when you’re looking at the process of an object, it needs to be examined from its biggest form to its smallest parts, not from its small parts up to its biggest form.

make sure that each section builds on the previous section

Ensure that a section doesn’t require knowledge that is explained later in the document.

make sure they are ordered around why, not time

Process is ordered around why, which is concept based, while instructions, process’ close neighbor, are organized around time. Avoid creating an outline that is ordered around time.

repetition:

topics

Process rarely returns to ideas again and again, so reorder topics to cover once.

rules

When lots of ideas all have the same rule, collapse the topic into something easily visible/understandable (like a table), and use the rule. Repeating the same rule suggests an improper organization.

Oops, I forgot to add that idea, now what?

If, after you’ve completed your outline, you realize that you ought to include additional content, then you need to restart your organization process back at step 1 so that you can place this new content in the correct place in the outline. Put the forgotten content in your mind map, then continue with the numbering ordering step.

You always want to reassess the order of information if you add content later. Rarely can you add content at the end of a document and make it work.

For instructions, you generally just need to research the steps or execute them yourself to understand what needs to be done.

Group concepts from your brainstorming output/research into larger ideas to generate an outline.

The most common process writing you’re already familiar with is a textbook (or any of these lecture notes about Technical Writing). Each section you read tells you a bit more about the topic. As you read along, you build a knowledge base to add to what you already know about the topic. You can understand the ending because you’ve read all the parts before. Not only do you understand the topic, but you understand your role. For example, in these lecture notes, you understand how to create technical writing patterns.

A table of contents is not a required element of process writing, but when it is included, it helps the reader skim for the information they are looking for when they return to the document. The first time through the document, they would still most likely read the entire document or at least skim each section.

There’s no section called “Introduction” in process writing. Instead, process writing begins with a purpose identifying why this information is being provided for the reader.

The purpose statement may or may not have a heading. When it does not have a heading, the purpose paragraph would begin immediately after the title or subject line. When it’s in a section by itself, the section heading is not named Introduction; instead, it is named Purpose or some other word that gets that point across.

How do you decide? If the purpose statement is more than one paragraph in length, then use a heading for it.

In the purpose statement, you need to explain why the reader needs to read this document – tell them what they need to understand. The purpose needs to orient the reader to the body sections that the document covers.

Purpose Orientation Sentence

When you have a TOC, that orients the reader. If you do not include a TOC, you need to include a separate sentence at the end of the purpose statement that explains what major body sections are covered in the document.

Never include both a TOC and this last orienting sentence, since that duplicates the information, and duplicated information annoys the reader.

Headings and SubHeadings

Each of the details in process writing have their own headings (or subheadings). Headings need to be clear and descriptive; the reader ought to be able to read the heading, and when they know what it covers, be confident that when they skip reading that section, they are not miss anything.

As with other technical writing patterns, you cannot use oneword or onephrase headings (there are rare exceptions). Oneword headings are too vague to tell the reader what is covered in that section.

The best way to make sure that the reader knows what is in the sections is to use headings that are phrases starting with verbs; use gerunds (verbs with an –ing form) to help the reader understand what the section covers. Do not use the command form of the verb – that puts the rule into the heading, and this type of process writing does not start with the rules – people tend not to read the section if you give them the rule first, because they think they know all the why, and you want to make sure that they read your process.

The phrase this section covers can be found after a Heading 1 (first heading in a Table of Contents) when there is no other way to introduce the section. A sentence that begins with this phrase orients the reader as to the contents of that major section of a document.

Do not use this phrase when these conditions apply:

· You have other introductory material to discuss after the Heading 1 that would orient the reader regarding that section.

· It is not a Heading 1 section (e.g., it is a Heading 2 or lower).

Body Content – Why, Then Rule

Process first explains why things are the way they are (including details of what that means and maybe examples) followed by the rule (which tells the reader what to do based on their understanding of the why).

To say something is important is not an adequate why explanation; instead, saying it’s important defines a rule using passive voice.

Rules are written in 2nd person POV, directly telling the reader what they need to do. Avoid passive voice when writing the rule.

In rare cases, the why followed by rule pattern may generate overly awkward phrasing, in which case, that can be reversed (rule, then why).

The why/rule is not written in terms of a “If..., then...” statement – the if/then structure implies a choice, and in process, the rule is not a choice, it’s a best practice. If you find yourself wanting to use if, then see if using when works instead, as that is a stronger bestpractice language.

It’s best to always separate the why/rule into separate paragraphs to make it easier for the reader to skim the content. When the reader understands the why, in many cases the rule is obvious, so they could skip it and move on.

It’s true that instructions (or commands) leak into process writing, but always try to first explain why before explaining how or what to do. The reasoning has to do with human nature. When you tell someone what to do and they don’t really like the idea or don’t want to do it, they will dismiss the command. But instead, when you first explain why things are the way they are, followed by the command (aka, the rule), then the reader will more easily follow the instructions. For example, when some people see a sign that says “Don’t park here,” the first thing they want to do is park there, especially when they can’t find a place to park. When they see why they are not supposed to part there, such as when the sign reads “Reserved for Electric Vehicles,” they are much more likely to follow the rules.

Paragraph Length

You should always have small paragraphs in process writing because they are easiest to skim. Small paragraphs in process writing are defined as up to 4 full lines of Times New Roman 12 text with 1” margins.

At the end of a process document, there’s no Conclusion, Summary, or other section to wrap up the content. It just ends.

The primary goal of a conclusion in technical writing is to answer “Now what?” should the reader do. In the case of a process, there are no further steps, so there’s no conclusion.

Writing that has no prescribed ending can be hard for some authors, especially those who are used to wrapping up their work between the bookends of an Introduction and a Conclusion, but in process documents, that is how it is done.

The Purpose of the Technical Writing Dictates the Pattern

Technical writing is written for readers so that they can get the information they need to do their job, which means that the reader can’t get their job done until they get the information they require.

Therefore, you need to organize the information in the most efficient pattern that the reader is looking for. Within each pattern, you need to further organize the information with headings and small paragraphs so that the reader can scan/skim easily for the information they are looking for.

Instructions are organized in stages and steps.

The most common example of instructions is online help. Take a moment to bring up the help of any product you frequently use to see how these instructions are organized. You probably even know that you can click on the question mark (?), which is usually the icon or signal for help.

Be sure the title of the instructions clearly explain what instructions are being provided.

A table of contents is not a needed unless the instructions cover multiple steps that span many pages (e.g., an installation manual for an encryption key server).

There’s typically no section called Introduction in instructions. Instructions begin with a purpose statement that identifies what the instructions are. This purpose could be a title, subject line, or heading.

Infrequently, this heading is followed by a brief (e.g., onesentence) paragraph introducing the context of the instructions to follow.

Instructions are organized by breaking down a larger task into stages ordered by time. Each stage is its own heading.

Each step is numbered. Each step begins with a command form of the verb. Under each heading (stage), keep the number of steps low, so that it’s easier for the reader to keep track of where they are.

When writing instructions, especially those that involve electricity, then it’s important to include cautions, warnings, and dangers. Use these standard definitions:

Caution – possibility of damage to equipment or materials.

Warning – possibility of injury to people.

Danger – probability of injury or death to people.

The primary goal of a conclusion in technical writing is to answer “Now what?” should the reader do. In the case of a process, there are no further steps, so there’s no conclusion.

Writing that has no prescribed ending can be hard for some authors, especially those who are used to wrapping up their work between the bookends of an Introduction and a Conclusion, but in instruction documents, that is how it is done.

There are several basic rules you should follow when writing instructions so that you are clear, concise, and accurate:

· Provide introductory information: definitions, notes, cautions, warnings, dangers.

· Provide a “getting started” checklist or “gathering materials/information step” when appropriate.

If your instructions require the user to gather materials or information beforehand, let them know what they will need to complete the instruction before they get started. Do not leave readers stranded midstep.

Use numbered lists when the order is important. Otherwise, use bulleted lists.

Notice that this list (and most of your lecture notes) use bullets, not numbers. Numbers imply that each line must follow the one before it.

Place one action per step.

Start each step with a verb.

Each step must be parallel. Notice how this list of instructions starts with the same tense of verb; this helps the reader as they scan the list of steps – they will know what each step does just from that one word.

Remove extra information from each step.

Provide that additional information in a separate, unnumbered/bulleted paragraph at the same indentation level. Again, notice how this rule is modeled with this paragraph and the previous paragraph. This allows readers to quickly scan the list of actions that need to be taken.

Watch for hidden instructions.

Hidden instructions tell the user to do something out of sequence. Recipes are a common place to find hidden instructions; for example, Step 1: Beat the flour and eggs for 3 minutes, then add the creamed butter and sugar. What is labeled step 1 should be step 2; step 1 would be the instruction to cream the butter and sugar.

Match the pace of your instructions to your audiences’ technical capability.

Include graphics, such as screenshots, as appropriate.

Sometimes, a screenshot or illustration can save you a great deal of struggle finding the right words to convey information, especially if you are conveying directional information. See the lecture notes “How to Interpret the AntiPlagiarism Scores” “Using MS Word’s Reference Manager” for examples.

Avoid embedding a clause in the middle of the instructions, as they force the reader to reconstruct the command.

Select your words carefully.

Users expect more precision and accuracy with instructions. Do not use vague words or phrases:

· don’t use a little while – use 5 seconds

· don’t use increases – use doubles or triples

· averages aren’t specific – use a range (e.g., 510 seconds)

Avoid sentence constructions with dangling modifiers (where the subject isn’t clear).

Use consistent punctuation.

Steps are complete sentences, so they have periods. Fragments, words, and phrases on bullets do not have punctuation.

Organize your instructions so they are not one long list.

This list could be divided into pattern instructions and grammar/style instructions to break it up.

Break instructions up into stages and steps.

Instructions are seldom read through. Group steps under task headings.

Test your instructions!

Once you’ve understood the basic process pattern, there are many ways in which you can change it based on your situation. For example:

· On the job, write process documents as you make decisions about a project’s design. This way, when new people come on board, they can read the decision documents and understand why things are the way they are with the project. This is so much easier than you having to later remember what standards you agreed to or why you decided to go with a particular decision. In addition, the new team members can get up to speed much faster.

Not all process documents are written as why/rule. Sometimes, once the reader understands the why, the rule can be obvious, and readers don’t like reading duplicated information – in these cases, the rule may be dropped.

Textbooks are a good example; they are a form of process writing, but they do not have all the explicit rules. Notice that many textbooks also break the rule of small sections, to the detriment of the student.

Sometimes, you can merge both the process and instruction patterns into the same document. For example:

· a car owner’s manual – these have an instruction focus, so they start with the process description, followed by the stepbystep instructions

· tutorials – these have a process focus, so they are organized by process, but include numbered instructions within the sections as needed

The problem/solution pattern uses a variation on the pattern – the sections are organized with the rule as the heading and the why as the body content.

Once you’ve understood the basic instruction pattern, there are many ways in which you can change it based on your situation. For example:

Write instructions for online help.

Consider how understanding instructions can help as you write code where users are entering information into a form. How might you help the reader when they use the cursor to roll over something? Maybe you can provide “justintime instructions?” Or how might a popup tip help orient the reader?

1

14