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)