Reflections on a Syllabus Technical Writing (CMPE 185) Kevin Karplus

25 April 1994, minor revisions 13 Oct 1994

Board of Studies in Computer Engineering University of California, Santa Cruz Santa Cruz, CA 95064

In my first quarter at UCSC, when we were redesigning the curriculum, my experience in reading design reports at Cornell led me to insist that all engineering students take a course teaching the type of writing that engineers do. All the other faculty agreed with the need, as long as I was willing to teach the course.

The course has been a challenging one to teach, both because of the diversity of the students taking the course and because of the workload involved. For example, in Spring 1989, Dan Scripture and I had 63 students in the class, with over 20 different native languages. Generally the class has around 45 students, and 10–12 native languages.

1 Course Goals

The course is unusual, in that it is aimed specifically at computer engineers and computer scientists. Most technical writing courses are either aimed at all scientists and engineers, or at technical writers who have a good writing background but a weak technical background.

There are several goals for the course:

• To make students comfortable in giving written and spoken presentations of technical material in a variety of styles.

• To make the students aware of their audience when they write, so that they can choose the material and style deliberately to meet the needs of the reader.

• To extensive practice and detailed feedback on their writing, so that all students who pass the course are capable of clear, concise writing on technical subjects.

2 Team Teaching

I worked with Dan Scripture (a writing instructor) in creating the course, and have team-taught it with him four times, taught it by myself once, and taught it twice with other writing instructors. It has also been taught twice by Tracy Larrabee, together with Dan Scripture. The least successful quarter was the one where I taught the course by myself.

Most technical writing courses are taught by writing instructors who have no technical background, or, less commonly, by technical faculty with little experience in teaching writing. The team-teaching approach that Dan and I developed has been very successful in combining the skills of the two instructors. The approach has also made it easier to transfer the course to new teachers.

The expense of having two instructors is fairly easy to justify, as the standard course size for a writing instructor is usually around 20 students, and the team of two can handle around 45 students. The course size is limited primarily by the time needed to provide detailed feedback on the writing assignments.

3 Textbook

We have tried several different textbooks, finally settling on one by Huckin and Olsen [HO91], because it has the best treatment of article usage, plurals, and countable and uncountable nouns (those aspects of English syntax that seem to give the greatest trouble to speakers of Asian languages). It also has good treatment of report structure, audience analysis, and the other aspects of technical writing that all the students needed to learn.

4 Workbook

Over the years, Dan and I have standardized the writing assignments to the point where we can have the students purchase a workbook with all the assignments. The workbook gets some revision each time the course is taught, but the assignments have not changed much in the last four years. The workbook is now about 84 700-word pages long, though it has been as long as 128 pages.

This year, we experimented with delivering the workbook electronically, instead of on paper. This encouraged the students to learn to use xdvi and dvi2ps early in the quarter, but it seemed that more of the students were attempting to do the assignments without reading them—making precisely the mistakes we warned about in the assignment. I’ll try electronic delivery again, but warn the students earlier about the need to read the assignments.

Despite reusing the same assignments every year, we have had almost no problems with students plagiarizing, as we require first drafts as well as final papers, and concentrate on the rewriting process in class.

5 Peer editing

To get the students used to the cooperative approach to writing used in industry, we have them read and comment on drafts of each other’s papers on almost every assignment. We spend six or seven of the 29 available lecture times on peer editing, and the instructors circulate around the room during the peer editing answering questions and assisting with the editing.

We have tried two approaches to peer editing: having students work closely with a partner on the editing, and anonymous peer editing, where the students pick an unlabeled draft at random to comment on. Both approaches work well, though there is a tendency for same-language students to work together when partners are chosen, resulting in considerably less feedback about language-specific problems with English as a second language.

On one assignment this year, we tried having students take the drafts home over the weekend and e-mail comments to the author. This produces much less useful comments than the in-class peer editing.

6 Assignments

The students have ten written assignments plus an oral presentation in the 10-week quarter.

We start the quarter with a résumé and job application letter. This assignment allows us to introduce the importance of considering the audience, of selecting which material to present, and of formatting the material for ease of reading. We also talk about the cultural context in which the material is read, since many of the students come from cultures with very different standards about how one presents one’s accomplishments. The students find this assignment extremely useful.

Our second assignment is a short in-class assignment, to read another student’s job application and résumé and write a short memo recommending that the student be interviewed (or not be interviewed) for the job. This assignment give the students a chance to look at the writing they have just done in the role of the audience, rather than the author, and gives us a chance to see how the students do under time pressure, when they don’t have time to get help with their writing.

We then start a sequence of three assignments that are directly tied to the sort of writing the students are most likely to do after they graduate: in-program documentation, description of an algorithm in the form of a consultant’s report, and user documentation for beginning computer users. Originally we started with the user documentation (the least technical assignment) and ended with the in-program documentation, but this year we tried reversing the order, since the in-program documentation, although the most technical, is probably also the most familiar format for the students.

The in-program documentation involves adding comments to a backtracking search procedure (usually to solve the knight’s tour, but occasionally to solve the eight-queens problem) taken from Niklaus Wirth’s book Algorithms + Data Structures = Programs [Wir76]. Wirth’s external documentation is given to them to explain the procedure, so that they do not have to decipher Wirth’s extremely poor choice of variable and procedure names.

The main goals of this assignment are to get the students to recognize the importance of documenting data structures (rather than just code) and to document the intent and effect of procedures, rather than just translating the code into English.

Although I cannot claim that students automatically transfer what they learn in this course to their programming in other courses, I believe that some gentle reminders that they will be evaluated on the quality of their in-program documentation in upper-division project courses would help a lot in getting the students used to considering the documentation as a normal part of the job.

The algorithm-description assignment asks the students to play the role of a computer consultant who has to recommend a change in algorithm to a client. This exercise is the first one in which they have to write to multiple audiences: the executive who is paying for the report and the entry-level programmers who have to implement the recommended changes. Because the course has only minor programming prerequisites, we use the simplest problem we could think of that offers multiple solutions: sorting a database by zip code. The students are free to choose any reasonable sorting algorithm, but most choose heapsort or quicksort, both of which are fairly difficult to describe to an entry-level programmer. The students often come away from this assignment with a greater appreciation for the writing in their textbooks, having discovered how difficult it is to explain data structure invariants (the heap property) or recursion.

The naive-user documentation assignment is to write a manual explaining e-mail (the Berkeley Unix mail program) to an audience of executives and clerical workers. The emphasis in this assignment is on organizing a document by task, rather than be program feature, and on selecting the appropriate subset of the features to describe. The students are often embarrassed to discover that they do not know how to do many of the tasks routinely expected of clerical workers (like maintaining a mailing list, forwarded incorrectly addressed mail, and mailing previously entered memos). This is perhaps the most difficult assignment of the quarter, since it involves writing for an audience very different from the students themselves.

The library puzzle and the survey article are an attempt to get students to use the bibliographic resources of the University to find things on their own, rather than relying on textbooks and professors for all their information. One of the big weaknesses of an accredited engineering curriculum is that it relies heavily on spoon-feeding the students information, and does not require much independent research. Most of the students have little idea how to find journal articles or conference papers in the library before taking this course. Luckily, UC has the INSPEC database (which includes Computer and Control Abstracts) available free to the students, so they get exposed to modern bibliographic search, rather than archaic printed indices.

In earlier years, we put the survey article much earlier in the course, and used it as a writing sample to determine which students would need extra help from writing tutors. Students resented the assignment, finding it too much like high-school papers. Pairing the assignment with the library puzzle and emphasizing the library research techniques has made the assignment much more palatable to the students.

The last several weeks of the quarter are all connected to the students final report. They have to write a proposal memo for the project they plan to do, write document specifications for the project, submit a a progress report, present the material orally, and write the final paper itself.

We do not choose the topic for the students—they have to select one and get us to approve their proposal. Generally about 80% of the proposals are accepted immediately, with most of the remainder being required to narrow their focus substantially. The papers are usually either library research (often an expansion of the survey article) or design documents for projects students have done in other classes or at work. A few of the students choose to write user’s manuals, though this is much less popular.

We encourage group writing projects for the final project, and teach the use of the document specification (an outline plus an audience analysis) as a management tool for scheduling the writing and dividing the workload.

The progress report is used to give the students an earlier deadline to keep them working on the final project, to give us feedback on how the students are doing, and to give us a chance to discuss honesty and engineering ethics. We talk about the need for honesty and clarity in progress reports, show a videotape of Roger Boijoly talking about the Challenger disaster, and discuss various strategies that engineers can use to keep their integrity despite the pressures that may be put one them by employers.

The oral reports are short (usually about seven minutes per student), but are generally as good as or better than the presentations one sees at professional conferences. We teach the students to select material and vocabulary based on what their audience knows and needs to know, project their voices, look at the audience, not stand in front of their transparencies, use large enough fonts, not clutter their visual aids, rehearse their talks with a timer, and generally avoid the mistakes that plague engineering presentations.

The final reports themselves are often quite long (though we encourage conciseness, the students often have a lot of material they want to include), and grading them in time for the University grading deadlines is often quite challenging.

7 Workload

All the instructors who have taught the course consider rapid feedback on the assignments important for the students’ learning. Since there are ten written assignments plus an oral report in 10 weeks, the grading load is substantial. In recent years, we have generally had two instructors and a TA splitting the grading for 45 students, making a load of about 15 students per grader, which is substantial, but not unmanageable. The highest grading load over the years was 31 students per grader (63 students, two instructors, no TA), which turned out to be an unsustainable load.

The workload is high for the students as well as the instructors. We warn the students that we don’t expect them to enjoy the class, but that if they work hard they will find that they really can write. Luckily the Computer Engineering majors are willing to work hard, and the failure rate is quite low (maybe 2%).

8 Summary

It has been very heartening to see the improvement in students’ writing in the course of a single quarter— often going from barely comprehensible to excellent technical presentations. I believe that the writing improvement has also been visible in other courses, as many courses require final project reports. Certainly the reports I have seen in the VLSI Design Project course have been much better than the corresponding reports that I got at Cornell.

I have had engineering students tell me after they graduated that the technical writing course was the most useful single course they took. Although they have dozens of classes with math, science, engineering theory, and design practice, this is the often only class in which they pay close attention to writing and speaking skills.

References

[HO91] Thomas N. Huckin and Leslie A. Olsen. Technical Writing and Professional Communication for Nonnative Speakers of English. McGraw-Hill Book Company, New York, 1991.

[Wir76] Niklaus Wirth. Algorithms + Data Structures = Programs. Prentice-Hall, Englewood Cliffs, New Jersey, 1976.