Barker, Chapter 3: Writing to Guide—Procedure

Guidance information is also known as step-by-step instructions how-to instructions, or procedures, and makes up the heart of all task-oriented documentation systems. Procedures consist of a mix of explanations and steps; the job of the designer or writer of these is to balance these elements.

Guidelines

1. Relate the Task to Meaningful Workplace Activities

“A procedure is a step-by-step series of commands for accomplishing a meaningful operation with a software program” (p. 64). The goal of writing a procedure is to see it as a part of larger activities. Procedures are the operation part of the activity/action/operation model examined in Chapter 1. The job of the writer is to clarify how the procedures fit into the larger picture in the user’s workplace.

2. Determine How Much Information Your User Needs

How much information users will need depends on the difficulty of the task, and their experience. Identifying both of these aspects will help the writer decide whether to make the procedure richly detailed or sparse. Layering is “a formatting technique that allows for different levels of information (beginning and advanced) on the same page” (p. 87) and caters to both levels of users and levels of information.

To enrich procedures, consider adding the following:

· Screen shots (show the actual user interface, what menus to display, and what choices to make)

· Cautions and warnings (alerts user to be careful of damaging product, losing data, compromising performance of system, and possible harm to humans as a result of errors with software or equipment)

· Tips for efficient use (suggest alternatives, workaround, and helpful applications; can also elaborate a step or command)

· Tables showing options the user can take with a specific task (organize information and present it efficiently: features and uses, terms and definitions, setting names and options, users and program sections tables of contents; keep tables simple and cite them in the text; use descriptive, performance-based column titles)

· References to other sections of the manual or resources

· Explanations

· Cross-references and links

· Icons

· Graphics showing program concepts

· Keystroke combinations

· Examples

· Footnotes

3. Choose the Appropriate Procedural Format

Choose from standard, prose, or parallel; it is a good idea to stick to one.

· The standard format consists of steps, notes, screens, etc, aligned on the left margin.

Advantages: It is recognizable by users, there is an easy flow from one page to another, it is easy to renumber and test, and it is easy to see the steps using a hanging indent.

Disadvantages: It may occupy a lot of space and maybe confusing if complex and simple steps need to be mixed.

· The prose format includes steps in sentence and paragraph form; a conversational tone occurs in programs with simple tasks and a simple interface. Bold and italics are used for command verbs, function keys, buttons, and text for the user to type in.

Advantages: It is conversational and relaxed in tone, saves space, clarifies simple, basic steps, and accommodates experienced users.

Disadvantages: It buries the steps in paragraphs, precludes lengthy explanations of individual steps, can’t accommodate graphics for individual steps, and doesn’t offer much support for novice users.

· The parallel format is useful for programs that include complicated data fields or dialog boxes and programs that require the user to move from one field on a screen to another, filling in each one along the way. Writers and designers should keep the terminology consistent, cue terms to the screen, discuss one screen at a time, use plenty of examples, and explain to users how the format works.

Advantages: It can help users stay organized, works well with shorter procedures, and is good for filling out complicated screens and dialog boxes.

Disadvantages: It does not present information in a step-by-step, task-oriented manner, can’t be used for all procedures because it is specialized, may confuse the user who gets lost moving between steps and screens, and has to fit on one page.

· For embedded help, a writer working with a programmer put tags into both the program and the help system. It displays procedural information as a part of the interface of the system, and, unlike conventional help, is not a separate program. Embedded help is useful for tips for efficient use; cue cards; short, animated demonstrations; and trouble-shooting tips. Types of embedded help include flyout help, interactive flyout help, do it for me help, field-level help, interface help, pop-up definitions, and roll-overs (p. 79).

4. Follow a Rhythm of Exposition

This means a pattern of step, note, and illustration. First give a command for a step, then say how the program will respond, then illustrate what happened, then tell the next step.

5. Test All Procedures for Accuracy

Test the pacing and format for the desired effect. Perform evaluative tests, where an actual user or prototype of a user actually performs the steps.

Discussion

What Constitutes a Procedure?

“Procedures are often rooted in the features of the software program” (p. 81). But in the office or the business, these features can differ greatly from the uses. The writer or designer should consider the features as the tools the program provides for the user. The procedures result from putting the functions of the program into a usable set of steps that do the user’s work. Procedures usually follow a chronological sequence, with a beginning and an ending. Kinds of guidance information include installation (which is usually accompanied by a wizard, which is the personification of a guide or assistant), maintenance, and repair, but most procedures focus on the actual operation of the program, the day-to-day uses.

How Does a Procedure Work?

The task name identifies the program in performance-oriented language.

The overview serves first as an introduction and describes the use of the procedure. Using informal language, it should prepare the reader to perform the steps, by indicating necessary skills and conditions. Second, the overview directs the user once he or she is started with the procedure.

The steps give the user tools to use and actions to take with the tools. In writing steps, numbers should be used as opposed to bullets, and numbered steps should not include renumbered actions. In notes and explanations commands should be avoided and imperative verbs preferred.

Elaborations comment on the steps as they get performed. They can include possible mistakes and how to avoid them, how to perform procedures efficiently, alternatives (keystrokes, toolbars, function keys), definitions of terms, how to tell if a step was performed correctly, where to look for supplemental information. Elaborations should be phrased in an active voice and should refer to the program.

Options are optional commands or keystrokes and should be presented in a table.

Screens illustrate to the user the tool in use or the goal or results of an action. They can show an overview, a partial result, a final result, dialog boxes, toolbars, and menus.

Dianna Cowles, Robin Erickson, Anna Ignatjeva

Campbell: Chapter 3

Isn't There a Law Somewhere?

This chapter covers the legal implications and considerations of writing policies and procedures.


Basic Overview

It is important to understand how statute and case law may affect your policies and procedures (P&P). It's not necessary to be a lawyer, but you should run any questions by your legal advisor.

You Can and Will Be Sued

Problems can occur when:

• "Procedures used by customers or employees are unclear, imprecise, or poorly worded"
• "Your policy or procedure violates some law or legal precept, intentionally or unintentionally"
• "The wording of your P&P restricts the organization's ability to act"
• "You have written P&P but don't use them or don't enforce them consistently"
• "You fail to state who is responsible for or what the consequences of noncompliance are"
• "Your policies or procedures are incomplete, in improper order, or inaccurate"

(Campbell, 58-59)

Some employees may have difficulty understanding your P&P due to language barriers or literacy problems. As the writer, you have a special obligation to help them understand, either by writing at an appropriate reading level or by offering translation.

Types of Violations

A tort, or an act that violates a law, can occur if your P&P violate safety regulations, fiduciary laws, fraud statues or public policy. Public policies are actions that may not be technically illegal, but "are recognized as being in the public interest."

Negligence is often more of a concern when writing procedures, where there are liability concerns or the possibility of injury or death due to poorly written operating procedures.

Breach of Implied Contract - Because P&P, whether written or verbal, can be considered an "implied contract", violating them can leave you open to prosecution for breach of implied contract. These cases often involve disciplinary or termination matters.

Disclaimers

Disclaimers can offer some protection. For example, a handbook or manual might contain a disclaimer that states that the "contents may change and are not contractual."

Manuals vs. Handbooks

The difference between the calling something a manual or a handbook may seem insignificant. However, from a legal standpoint, a "handbook" is often considered to be more widely distributed than a manual, which may imply that it can be considered contractual. The term "user's guide" implies that the contents contain guidelines; it is being used more often since the term avoids the appearance of making promises or implying contracts.

What the Courts Want You to Do

Businesses are expected to "operate in a safe, reasonable, and fair manner." They are expected to clearly communicate and enforce the P&P.

How to Protect Yourself

To avoid lawsuits, it is important that the P&P are well written, understandable, and accurate. They must follow laws and regulations and should contain disclaimers and words that express management's right to make changes and take alternative action, if necessary. The rules for noncompliance should be articulated and followed consistently. Informal and written rules should also be considered.

Other issues:

You can be accountable in a court of law for Informal and unwritten rules.
Old, outdated P&P can still get you in trouble. It's important to keep your P&P updated.

Robert Connors: The Rise of Technical Writing Instruction In America

I. The Early Years: 1895-1939

Robert Connors’ article on the history of technical writing instruction was published in the Journal of Technical Writing and Communication in 1982. It is an extensive narrative on the progression of technical communication, with an emphasis on academia.

Connors writes that technical discourse has existed ever since the use of tools and man’s communication about them. Technical writing can be traced historically back to the Sumerians and Roman Empire. Systematic instruction of technical writing, however, is still a rather recent development. Connors’ article is an attempt to trace instruction in technical writing from its beginnings to its present state.

Engineering Education in the Nineteenth Century

Technical writing courses have been taught in American colleges since the late nineteenth century; however, the first courses were sparse. The Morrill Acts in 1862 and 1877 “founded and promoted the land-grant agricultural and mechanical colleges that were to make college education available in the later nineteenth century to a hugely increased percentage of the population” (4).

Studies in math, modern languages and literature, liberal arts, and more were added to college curriculum alongside Greek and Roman philosophy and literature. The Civil War made way for this change as engineers were seen as important figures, and the Industrial Revolution meant that schools of engineering were a part of natural progression.

Still, upper-level writing courses were rare in the nineteenth century. Before 1870 an engineer would graduate with little education in writing. In fact, many engineering schools at the time dropped humanities courses almost completely. What remained was the basic of all writing courses—freshman composition. It was believed that taking freshman composition would be enough for engineer to get by.

Engineering education became more sophisticated as the nineteenth century was ending, but it still did not place emphasis on the linguistic needs of its students. “The Society for the Promotion of Engineering Education (SPEE) was founded in 1894, but it had no members from English departments until after 1905, and in general, engineering schools acted as if their students needed none but technical courses” (5).

At the start of the twentieth century, articles condemning the illiteracy of engineering students began to appear in engineering articles. It wasn’t hard to see why this controversy started. Freshman composition courses were simply too general. On top of that, J. Martin Telleen explained in 1908 that freshman English courses came too early in their careers. He also noted that English and engineering faculties rarely engaged in interdepartmental cooperation.

Samuel Earle and Early Technical Writing Theory

“The period 1900 through 1910 was the gestation period for technical writing courses” (6). Some engineering schools actually created English departments to serve the special needs of students.
T. A. Rickard’s A Guide to Technical Writing ­(1908) became the first important textbook on technical writing. It dealt mostly with usage, and while it was used for college classes, it was more meaningful to practicing engineers. In 1911, the “first genuine technical writing textbook written for use in college courses,” (6) was published. The book, called The Theory and Practice of Technical Writing, was authored by Samuel Chandler Earle.

The Theory and Practice shared few elements with composition texts of the early twentieth century. “It grew out of courses in ‘engineering English’ that Earle had been teaching since 1904, courses that were perhaps the first recognizable technical writing courses” (6). Earle became the philosophical voice of the early technical writing movement. He defended his position on general composition, stating that it was not enough for engineering students.

Earle also commented on the division between English and engineering teachers, stating that the sour attitudes between the two were immature and misguided. His idea was that continuing education in other subjects to further one’s career shows true devotion.

Earle’s influence on the education of teaching English in engineering school was monumental. The decade that followed his death saw great improvement in the growth of technical communication. “Between 1911 and 1920, the basic elements of technical writing courses as we now teach them were limned out at a number of schools around the country” (7).

Complaints about technical school graduates were prevalent by 1916, but engineering schools attempted to change that. A demand arouse, asking for a basic literacy in engineering graduates. Unfortunately, English teachers often used their own methods, and students ended up being taught literature along with writing. This resulted in a problem in understanding between English and engineering faculties.

“On the east coast there grew up a movement led by Frank Aydelotte of MIT whose aim was frankly to ‘humanize the engineering student’s character and his aims in life’ through literary study” (7). He stated that engineers should be able to write what they practice. Some schools taught English courses inhouse where faculty in both English and engineering worked closely together.

“During this period there were generally three sorts of English courses available for engineering students: the required freshman composition course, a sophomore literature sequence that was sometimes required, and the junior- or senior-level courses in ‘exposition for engineers’ that were the prototypes of today’s technical writing” (7). Problems arose immediately, though. Many students were not interested in learning to write or read, English teachers were often young and inexperienced, and the cooperation continued to lack between engineering and English departments.

The Formation of a Discipline

“Prior to 1912, there had only been two English teachers in the SPEE, but seven more joined that year… The Mann Report on Engineering Curricula in 1918 recommended more time spent on English, and by 1920, 64 percent of all engineering schools required some sort of technical writing course for their students” (8). At this point, engineering-only hardliners gave in and fit English into the curriculum.

At the start of the twenties, the amount of time devoted to technical writing increased, new courses were suggested, and new textbooks began to appear.

The first “modern” technical writing textbook was distributed in 1923 (English for Engineers). It was written by Sada A Harbarger of Ohio State University. The book is organized by “technical forms,” and this still remains the basis for most textbook organization.

Two new developments in technical writing—practical and philosophical—came about in the mid-twenties. The practical development focused on the writing of technical reports, and the philosophical development began to focus less on literature.

“A 1924 SPEE survey found that it was no longer necessary to urge the importance English for engineers… The survey also found that English requirements at engineering schools had doubled since 1914 and that more colleges were instituting technical writing courses each year” (9). At this point it became clear that English found a place in engineering education.

Expansion and Depression

Changes continued throughout the twenties: new textbooks appeared, and technical writing courses refined themselves slowly but stuck to relatively rigid forms.
“Another SPEE survey, in 1930, showed that of 1300 engineers and teachers, 95 percent approved requirements in English composition, 75 percent approved speech requirements and 45 percent approved literature requirements” (9).

The Depression during the early thirties hit engineering schools hard, and engineering teachers still did not give English teachers proper cooperation. English teachers were accused as being insufficient in teaching students. Regardless, technical writing courses continued to fill. Every year, more classes opened and new textbooks sold well.

A dissertation (later turned into a published report) by Alvin M. Fountain appeared in 1938, and the results of its survey/interviews “showed that of 117 engineering schools in America, 76 schools offered 93 different technical writing courses in 1937” (10). This report detailed course content, textbook use, and teaching methods. “The most important information… is that he shows how a technical-forms approach of a rigid and mechanical sort had become all but absolute by the late thirties” (10). The report clearly showed that technical writing was thriving. On the other side, though, the report had also shown that the teaching of technical writing had seen little progress, and the gap between engineer and English teachers widened.

II. A Discipline Comes of Age: 1940-1980

Developments During World War II

During World War II, it appeared that engineering English articles had ceased; however, the teaching of technical writing continued despite lower enrollments.

Two SPEE reports had no immediate effect, but later would “change the course of post war engineering education in America” (11). The Hammond Reports of 1940 and 1944 encouraged a mixture of humanities and sciences at four-year schools. The suggested program would be to have 20 percent or more of the student’s time devoted to humanities. By the early fifties, the “humanistic-stem proponents had achieved final victory” (11).

The Postwar Technical Writing Room

Technical writing courses continued to expand, especially after the war. Part of this had to do with students attending on the GI Bill. Another reason for expansion was due to the nature of the war—it was a technological war. Technical writers were needed to write manuals for airplanes, guns, bombs, and other machines. Technical writing became a job instead of a function.

After the war, technical writing became a profession as technological corporations opened divisions for technical writers—they realized that it was less cost-effective for engineers to design and write. Still, at this point, technical writing was not a major offered at colleges. Courses in the postwar era saw a rise in demand, and teachers tried to cope.

The late forties saw a greater expansion in the number of forms taught in technical writing courses; only gradually had business letters been added. By 1951, six different report forms were widely taught, and more than ten letter types were eventually taught. Manual writing also became popular, partially due to military influence, but also due to “the increasing number of technically-based consumer products American was turning out” (13).

A New Professionalism

The 1950s led way to the essential form of technical writing as we know it today. The Society of Technical Writers was established in 1958. The fifties also saw the industry’s taking notice of technical writing as a profession, and colleges gave serious consideration to technical writing as a standalone major. In 1958, Rensselaer Polytechnic Institute established the first master’s degree in technical and scientific writing in the United States.

Most campus technical writing programs were still plagued by the usual problems, but courses continued to be refined. The humanities requirements that were proposed in the Hammond Reports were beginning to be replaced by technical writing requirements. “By 1957, nearly all colleges offered a technical writing course, and 64 percent of engineering schools made such a course a requirement during the junior or senior year” (13). Required courses were more carefully constructed than past courses, and experimental teaching methods became more common. Most successful courses came from cooperative courses team-taught by English and engineering teachers.

“Mills and Walter conducted a survey of over 300 actual technical writing situations in industry, and from this survey came a number of changes in the approach that informed their textbook” (13). Two important assumptions had gleaned from their survey were

1. A rhetorical approach rather than the rigid “types of reports” approach that most texts used was best. Most reports are made up of several common processes: definition, description, explanation of process, etc.
2. The only good criterion for technical writing is “does it work?” This indicates that in technical writing as well as in other rhetorical forms, the writer-reader relationship is most important. (13)

Mills and Walter’s “Technical Writing reflected these assumptions and went on to be the most popular and paradigmatic text of the fifties, pointing the way to a new rhetorical approach to technical writing that was to revivify what had been in danger of becoming a sterile and mechanical course” (13-14).

Others also agreed that a reader-writer relationship was crucial in technical writing instruction. “A growing awareness that audience considerations had long been scanted in technical writing was one of the important developments of the 1950’s” (14). Critics condemned technical writing courses in 1955 for their dismissal of audience consideration.

The fifties also saw the expansion of technical writing into fields other than engineering. Departments such as agriculture, architecture, chemistry, pharmacy, and home economics pushed their students toward technical writing. The course was seen as a viable addition to the curriculum. Courses also evolved to include additional assignments and materials.

Breakthroughs and Problems

By 1959, technical writing textbooks were high in number. By the end of the fifties, textbooks replicated the rhetorical approach of Mills and Walter. Despite the long and honorable history, technical writing received little welcome from literary departments.

America began a war of technology with Russia after Sputnik was launched in 1957, and as the sixties opened there was a serious shortage of technical writers in the industry. Industries engaged in bidding wars for the few technical writers. The Society of Technical Writers changed to the Society for Technical Communication, and it still thrives today. “As a group, technical writers advanced greatly in both pay and prestige” (14).

College campuses still saw problems, however. Courses struggled to define themselves, teachers were unsure what to expect in their jobs, and students were getting more intelligent but were fewer in number as the sixties proceeded.

“Robert Hays investigated the nature of technical writing in 1961 in a widely reprinted essay entitled What Is Technical Writing?” (15) W. Earl Britton wrote the most comprehensive early definition of technical writing by defining it by subject matter, linguistic nature, thought process involved, and purpose. “Britton’s conclusion was that technical writing is defined more than anything else by ‘the effort of the author to convey one meaning and only one meaning in what he says’” (15).

This paved way for an awakened interest in the sixties. The first steps of empirical research into technical writing and the teaching of it were made. Researchers gathered and analyzed facts about technical writing in a scientific manner.

Despite this growth, the same old problems still existed with courses. Teachers continued to battle over whether to teach technical students to write or read and appreciate literature. In the sixties, technical writing teachers continued to be graduate students and low-level faculty members. Literary studies continued to be the interest of many technical writing teachers well into the seventies.

A major form emerged in the teaching of technical writing emerged in the sixties: the proposal. “During the late fifties and early sixties, it was estimated that industry spent in excess of one billion dollars per year on the writing of proposals, and the importance of this new form soon became obvious to the writers of technical writing texts” (16). The first textbook to tackle proposals was published in 1962: Siegfried Mandel and David L. Caldwell’s Proposal and Inquiry Writing. It was received well, and the proposal as a form soon spread to all texts.

Retrenchment and a New Sense of Identity

Well into the early seventies, a serious drop of students enrolled in engineering programs occurred, even though general enrollments were on a steep rise. Enrollments in technical writing courses shrank as well.

Despite the decrease, dedicated technical writing professionals teamed, and in 1970 “the Journal of Technical Writing and Communication was started, a journal which quickly became the most respected organ in the field of technical writing instruction” (16). The journal exclaimed the interests and tools of technical writers. “Tools became more sophisticated; in 1971 Stello Jordan and his associates published a two-volume Handbook of Technical Writing Practices” (16), which was considered the most sophisticated and complete technical writing guide ever published.
In 1974, technical enrollments began to rise again, and by the late seventies they went up an average of 10 percent per year (when college enrollments were becoming static). “The Modern Language Association, which had for over fifty years refused to recognize technical writing as a legitimate function of English scholars caved in during the midseventies and gave technical writing belated recognition in 1976” (16).

The demand was simply a result of the continuing need for technical communicators in industry. “A survey during the late seventies showed that over 50 percent of an engineer’s time was spent dealing with writing, and over 85 percent of professional engineers polled said that a technical writing course should be required of all technical students” (16). More departments continued to require a technical writing course. Teachers were not always rewarded, but many gained credit that had previously been nonexistent. Courses were filled, and many teachers found additional opportunities in consulting for industry, and consulting would help to improve in-class instruction. Available positions also became more and more available, and the seventies proved to be a good decade for technical writers.

Textbooks became more sophisticated and were made available for two and four-year colleges.
At the end of Connors’ article, he states that technical writing should be taken out of the hands of English teachers. It is interesting to note that at Minnesota State, our technical writing program is listed in the English department. As Connors would see, the instructors here do understand the separation of literature and technical writing, so he would most likely be pleased.

This article was not easy to summarize (as you can tell by this summary’s length). The amount of information that Connors wrote was concise, with every sentence containing a new thought. We thank you for your time in reading this summary!

Team 3 (Lori Hood and J.J. Carlson)

Barker, Chapter 2: Writing to Teach — Tutorials

Tutorials are designed to teach how to use something, such as new software. It may teach a beginner focused lessons on starting out, or it may teach an advanced user more complex focused lessons. Tutorials, like other software documentation, should be created with the user in mind.

Guidelines

There are seven recommended guidelines to follow for tutorial design:

1. Identify User Actions You Need to Support

Analyze the users of the program and their needs, including what they use on the job, what software features are essential, and what features are used frequently. Embedded tutorials are useful to detect important skill lessons, but it should be clear how to close the embedded tutorial if not needed.

2. State Objectives as Real-World Performance

The objectives of the tutorial should be stated in the module in terms of the user's performance. State exactly what will be learned in measurable terms.

3. Choose the Right Type of Tutorial

Types of tutorials include The Guided Tour, The Demonstration, The Quick Start, The Guided Exploration, and The Instruction Manual. The Guided Tour consists of an overview of the main features of a program. It can be online or in print. The Demonstration demonstrates specific actions in a program. Experienced users may use The Quick Start to jump right in to a program and start working with it. The Guided Exploration allows the user to determine the direction of the tutorial, exploring its options. Finally, The Instruction Manual teaches users step by step how to use a program, from basic features to more advanced ones.

4. Present Skills in a Logical, Cumulative Structure

It is not enough to prepare logical and organized lessons in your tutorials--you must also order those lessons in a logical and coherent way. Like other aspects of documentation, the proper order and structure will be determined through an evaluation of your user's needs, i.e., a typical-use scenario. Usually, the tutorial will progress from the general to the specific, the structure of which will mirror the typical user's workplace routine.

5. Offer Highly Specific Instructions

Instructions should emphasize scenarios that are familiar and applicable to the user. These scenarios should contain specific instructions to ground the user in the lesson. Keeping them grounded will help them fight feelings of insecurity they may be having toward having to master a new tool. Some examples of specific instructions include using concrete data, interface tools, screens, and specific commands. In addition, remove all distractions from the lesson, including page design elements that may interfere with the learning process.

6. Give Practice and Feedback at Each Skill Level

Giving users positive feedback in a conversational and positive manner will help orient them emotionally to the tool you are helping them learn and to the tutorial itself. Avoiding jargon and making liberal use of "you" and "we" will give the tutorial a "human touch."

Building consistent patterns gives predictability to the tutorial and reduces the amount of work the user must go through to understand the concepts that are being taught. Avoid alternative explanations because they may overwhelm some users and distract them from what they are learning. If feasible, build in practice exercises or quizzes into the tutorial to help keep the interest of adults who enjoy challenges and self-exploration.

Because most of your users will have competing demands on their time, keep the lessons short, about 10 to 12 minutes each. Also, let them know how to save their progress in case they need to shut the tutorial down and pick up where they left off at a later time.

7. Test Your Tutorial

Usability testing gives you necessary information about the effectiveness of your tutorial. If possible, test the tutorial in a real user environment. Focus the testing on the design elements, such as the cuing system and graphics. Perhaps most important, ensure that users can complete the lessons in the allotted time and that the lessons result in real learning.

Designing Tutorials

Because tutorials are designed to teach, the tone of the writer's persona must match the intended user to create a close relationship between the two. Because the goal of tutorials is to internalize work-related tasks and concepts, try to limit the scope of what the user is exposed to. This contrasts with other forms of documentation in which the writer attempts to be as expansive as possible. In order to narrow the scope of the tutorial appropriately, you must fully understand the needs of the user--which tasks are essential to them and which aren't? Without a thorough user analysis, it is impossible to narrow the scope of the tutorial appropriately.

Tutorial Users Need Special Care

Most of your users will be adults who have their own motivations for wanting to learn the tool that your tutorial is helping them master. For your tutorial to help them successfully, you must take into account the varied learning styles of your target population. As a tutorial designer, you need to understand how to limit the lesson times, prevent the user from being publicly humiliated for mistakes they make, give positive feedback, and make the user feel that they are self-directing their own learning.

Two Trends in Tutorial Design: Elaborative and Minimalist

The elaborative approach to tutorial design emphasizes reiteration to "bring the message home" to the user. Summaries, examples, and explanations all reiterate the learned material and may help the user retain and apply the knowledge they have gained. This approach is especially important for novice users with little-to-no experience with computers or the program being taught.The minimalist approach gives a nod to real human behavior: people often want to get off and running, without spending a lot of time in advance preparation. In the minimalist approach, the introductions and summaries are discarded because most readers will skip them anyway. To create effective minimalist documentation, use an action-oriented approach that is grounded in a workplace context that helps users recover from errors made and supports reading to "do, study, and locate."

Team 4 (Chapman and Lukkonen)

Campbell, Chapter 2: Where Do I Start?

In policies and procedures writing, we talk about the development process instead of the planning process. It’s important to develop the project instead of diving into writing, because if we immediately start writing, we may be missing something crucial to the project.

The four steps of development are

1. Planning
2. Analysis
3. Research
4. Prewriting

Each step should be covered, if even briefly, and all should be done in order. Outlining is not recommended because it wastes time and could cause errors.

Step 1: Planning

• A plan, in most cases, should be written
• This step is not always formal

Since every project has a deadline, a plan should be kept somewhat simple. For this, it is a good idea to plan the basics:

• Tasks
• Sequence
• Deadlines

Set a schedule

• List the steps
• Indicate team member responsibilities
• Make timetable estimates

A team’s size is important because too much work for few writers will make it difficult for the team to meet the deadline. Our text states the following when working with a team of writers:

• Select members with appropriate backgrounds or expertise
• Meet or talk regularly
• Establish ground rules
• Agree on assignments and responsibilities
• Establish a monitoring system
• Agree on deadlines
• Develop a team style guide

Be realistic: Make sure the plan is doable, and always check for conflicts and other possible concerns (such as other projects that have their own deadlines). A written plan should help address these possible road blocks.

Step 2: Analysis

In this step, the team should look at the project’s

• audience
• assignment
• context
• relevant research
• conditions for the work

Some concerns can be answered in analysis through the following:

• Look at who requested the project, and why the requested it. What led to the project’s conception? To what degree is the nature of the project? Is it technical or non-technical? Simple or complex?
• Know your goals. What do you want to result from the project? If you’re ever unsure, ask for more information (from knowledgeable sources such as the requestor).
• Know your audience so you can mold the document for them. What are their experience levels, interests, preferences, attitudes, and so on? How will they use the document?
• Know the project’s subject matter and its urgency. How big of an impact will it have on the organization? What are the conditions you will be working under?
• Go over important concerns with the requestor of the project. In this manner, update them regularly.

Step 3: Research

• First action here should be on matters of content.
• The amount of research here should be determined on what was found relevant in step 2.
• Ultimately, you will determine the amount of research.

Start with the most difficult research first as it will probably take the most time. This will give you time to ask questions and get clarification.

If it is possible, get information from experts who know the information you’re searching for. Also, talk with anyone who could provide input (such as the users of your document).

Relevant material should be read (books, articles, organizational files, etc.). And, of course, concentrate on critical information over anything else.

Step 4: Prewriting

Prewriting involves organizing the material, and this helps to speed drafting. This step is done before writing, and it is recommended to hold off writing at this point. An important question here is, “How do I convey this information to the reader in the clearest, most logical way possible?”

Content is key, so make sure all necessary information is gathered. The book suggests to practice mind-mapping (see example 2-8, p. 55) to gather and organize data. Mind-mapping reverses the process of outlining and allows you to focus on content issues first:

• It removes our creative side and brings all content to the forefront of organization.
• It helps you record your thoughts and knowledge at random.
• It is less likely that important information will be omitted.
• It may be easy to do, but it gets results.

Finally, in prewriting, you should develop a flow or sequence of the material that would be most logical to the reader. Will the reader use the information in a way that works for them and the organization?

Thank you, everyone, for participating in discussion on this chapter!

Team 3 (Lori Hood and J.J. Carlson)

Campbell, Chapter 1: What's a Policy, What's a Procedure?

What’s a Policy, What’s a Procedure?

You need policies and procedures because otherwise there would be chaos and frustration. Policies and procedures are the way an organization operates. Policies deal with the “what” and “why” while procedures deal with the “how.”

Policies are guidelines that regulate organizational action. Policies are used to explain an organization’s view on a certain subject or issue and why their view is what it is. Policies are up to each organization to decipher and regulate as long as their choices do not break any laws. Decision-making is the key in policy making, because if the organization doesn’t know what direction it wants to go in, the employees lose sight of what is important to the company and this can result in lost productivity and job loss due to the lack of clear direction.

Policies can be either ambiguous or specific, depending on the subject matter. It is up to the policy writer to determine when it is appropriate to be ambiguous and when more specificity is needed for certain policies.

Procedures are the normal method of handling things. Procedures tell employees how to go about their daily job in an appropriate and safe manner. Procedures are action oriented and can point out the consequences of not following procedures correctly. Procedures should be very specific, and oftentimes can be regulated by safety organizations such as OSHA, and will help employees to stay safe and in good standing while on the job.

Policies and procedures can be difficult to write because they require both an air of subjectivity and an assumption that the employee will take their own actions and position within the organization seriously and with regard to others on the job.

Policies and procedures should be carefully considered before they become “law.” They are not always appropriate, and they can sometimes lead to employees feeling micromanaged or result in more incidents because employees got “bored” reading through all the procedures and therefore didn’t. Be sure that the organization goals are clearly communicated, and employees will generally try to fit within those goals.

Written vs. Unwritten

Unwritten rules can sometimes be more preferred than written rules. We all have unwritten rules, whether we realize them or not, that come into our daily lives and work lives all the time. It is best to leave a policy or procedure unwritten when:

· It involves organizational culture and norms,

· It cannot be consistently enforced,

· It is potentially offensive or intrusive, or

· It simplifies another rule that employees already understand.

Sometimes, these unwritten rules DO need to be written down, but unless something serious has happened such as an accident or a complete disregard for even the ambiguity of the unwritten rule, unwritten rules are normal and almost expected in organizations.

What to Include in Policies and Procedures

It can be very hard to know what needs to be included in policies and procedures, especially when there are the aspects of keeping the rules ambiguous at certain times and specific at other times, or when there can be rules that do need to be written and those that do not. The audience is the key in determining what needs to be in your policy or procedure. Purpose is another big determiner in what is written. Writers need to determine what readers need to know as opposed to what they want to know. It is important to ask who wants readers to know specific policies or procedures, and if the writer can answer that question, it can be assumed that the policy or procedure NEEDS to be included. If information is interesting, but maybe not necessary, to the employee, that is information that they will WANT to know. Writers need to keep in mind that the readers of policies and procedures want to know what’s in it for them (WIIFT) – what it will mean to them and for them.

Discretion is key in determining the detail content of the policy or procedure. If a subject or topic is complex, or if the policy or procedure contains a legal aspect, the policy should be as detailed as possible to avoid questions or misinterpretations of the rule. Writers should be sure to do a thorough audience analysis before writing or updating policies because that is who the policies and procedures are directed at, and can help the writer to determine what level of detail is appropriate.

Manual or Handbook?

Once an organization has its policies and procedures written down, it is important to organize them into one place where employees will know where to go to find the information when they need to reference it. Many institutions call these organized books of information either manuals or handbooks. There are legal connotations associated with both of these terms:

· Manuals imply restricted circulation within an organization, and

· Handbooks imply general distribution.

If a writer is concerned at any point about a contractual issue, it is important to know the differences between the two as they could create legal troubles later.

Summary by Team 1: Amy Beeman and Jane Xiong