PBDS 606
Creating Technical Documents
NOTE: This is representative of the syllabi for this course. It is not necessarily the syllabus being used in any one semester.
Approach
In this course, we will explore different genres of technical writing, with a focus on creating pieces that are effective for their intended audience and purpose and are written in a clear, crisp style.
Focus on Audience: We will hone our ability to analyze the audience, purpose, and context for technical documents. The goal is to create documents that people can easily read and use for various purposes,to figure out a feature in a software program, to set up a coffeemaker, to operate machinery, to understand the differences between allergy drugs,in various contexts,under deadline, with a short attention span, in the kitchen, on a highway construction site.
Focus on Style: We'll do lots of writing in this course, from short, informal pieces to longer reports and proposals. We'll use Joseph Williams' book, Style, as a guide in honing our own writing style, and we'll get practice with different genres of technical writing with several brief writing tasks and three major assignments.
Focus on Professional and Personal Experience: Some of the most instructive elements of this course will be the experiences, ideas, and questions you bring as professionals and astute designers and writers. Our class discussions and assignments will combine what we know from our experience with theory and direction from articles and textbooks. We'll spend considerable time finding (out of class) and discussing (in class) samples,ones that you've created and ones that you find at home, at your workplaces, and through research.
Materials: Primarily, we'll use Writing for the Technical Professions by Kristin Woolever. I will also provide supplemental readings helpful in explaining topics, demonstrating effective strategies, or keeping up with what's current in the field.
Goals
The goals for our readings, discussions, and assignments are designed to help you:
• Gain experience writing and analyzing a variety of elements used in technical documents
• Develop a mode of analysis that you can use in the creation of technical documents, whatever role you play (writer, designer, or team leader) or whatever media you use
• Develop a clear, concise, crisp writing style and an ability to recognize and revise unclear or wordy writing
Expectations
Presentation of Your Work: Though we will move quickly this semester through a lot of material and writing tasks, I expect that everything you write, the samples you gather, and your discussion in class are all thoughtful, thorough, clean, and clear.
Collegial Discussions and Critiques: I expect that we will learn from each other,and, to do so, we all must be prepared for class, be willing to speak up about our ideas and experiences, and be willing to learn from each other. Periodically, we will engage in peer reviews of our writing, which will require the same kind of openness about your work that you'd have in a design critique.
Time: Throughout the semester, we'll need to find a balance between time constraints and the many topics in the course. I am willing to work with you to strike this balance.
Communication With Me
I am happy to meet with you to discuss our work in this course in person, on the phone or via e-mail. As an adjunct professor, I will be on campus late afternoons and evenings on Tuesdays and available to meet in person before class by appointment and after class for short discussions. For a discussion at another time, call or e-mail me.
Grading
I will evaluate your participation and work products using the same criteria a client or supervisor would use. Professional quality work is thorough, thoughtful, timely, and accurate, and includes credible explanations of anything out of the ordinary (such as inability to fulfill the assignment guidelines).
Assignments will be weighted as follows:
Several weekly (shorter) assignments and class participation 40%
• Short memos reporting on interim steps for larger projects
• Exercises on style
• Document analysis
• Definition revision
• Web site analysis and architecture
• Visual displays of information
• Portfolios
Three larger (comprehensive) assignments 60%
#1: Software documentation (group project using task analysis,
instruction writing, and user testing) (15%)#2: Proposal (15%)
#3: Report (a piece that uses several of the technical communication
strategies studied during the course) (30%)
Grading Scale
The larger assignments will be graded on a 1-5 scale, and the weekly assignments will be graded using a 1+, 1, or 1-. You have the option to revise weekly assignments that receive a 1- . The larger assignments may also be eligible for revision.
Class Schedule
January 28
Class Topic
Preparation for Class
Due
Week #1
Course Introduction
February 4
Class Topic
Preparation for Class
Due
Week #2
Technical communication
Woolever (p. 1-7)
Gurak supplement (p. 4-13)
Short explanation on the audiences and purposes of the most common documents you currently create
Understanding Readers
Janice Redish, "Understanding Readers"
Woolever (p. 13-16)
Checklist: Writing in Context
Introduction to Style
Lessons One and Two in Style
Woolever (skim chapter 5 as a preview of our discussions on style for the semester)
Discussion of samples
Bring in two sample technical documents from your workplace, home, the Web, or another profession
February 11
Class Topic
Preparation for Class
Due
Week #3
Adjusting to readers
Burnett supplement (p. 76-83)
Document analysis (Analyze the effectiveness of one of four documents based on strategies for meeting the needs of readers)
Organizing for Readers
Chapter 3 in Woolever
Definitions and Descriptions
Burnett supplement
(p. 327-348)
Style: Actions
Lesson Three in Style
Exercises 3.4 and 3.6 in Style
Discussion of samples
Bring in two examples of technical definitions: one for experts and one for nonexperts
Bring in one work sample (of your own from your workplace or from a class) suitable for analysis by a classmate
February 18
Class Topic
Preparation for Class
Due
Week #4
Instructions and Task Analysis
Riordan supplement, "Sets of Instructions" (p. 259-286)
Definition revision (Revise a poorly written definition using the strategies in the Burnett reading)
Collaboration
Woolever, Chapter 14
Mirel et. al., "Collaboration Between Writers and Graphic Designers"
Discussion of samples
Bring in one example of effective instructions for a household item, workplace process, or something in your field
Bring in another example of poorly written instructions
Introduction of assignment #1, Software Documentation
February 25
Class Topic
Preparation for Class
Due
Week #5
Writing and Formatting Instructions
Woolever, Chapter 7
Online Help
"Differentiating Between Print Documentation and Online Help" in Intercom, STC
Style: Characters
Lesson Four, p. 53-64
Exercises 4.1 and 4.2
March 4
Class Topic
Preparation for Class
Due
Week #6
Task Analysis
Riordan supplement, "Sets of Instructions" (261-263, "Analyze the Sequence)
Task analysis for software documentation project
Software documentation project,groupwork
Document Design
Schriver supplement, "What is Document Design?" (p. 1-11)
"Revealing Your Hidden Value" in Intercom, STC, February 2003, p. 18-19
Style: Characters
Lesson Four, p. 65-75
("The Objective Passive" through the end)Complete two exercises in 4.3, 4.4, and 4.6.
March 11
Class Topic
Preparation for Class
Due
Week #7
Software documentation project,groupwork
Individual assignments for group project as determined on March 4
User Testing
Schriver supplement (read p. 448-455; review examples on p. 460-469)
Integrating Text and Visuals
Woolever, p. 95-109
Gurak supplement
Schriver supplement (p. 407-411 and examples 1-4 on p. 414-415, examples 1-3 on p. 416-417, "Setting the Wrong Stage" on p. 428-430)
Style: Cohesion and Coherence
Lesson Five, p. 77-88
(read through "Integrating Principles")Complete both exercises in 5.1 and 5.2.
March 18
Class Topic
Preparation for Class
Due
Week #8
Visual Functions
Burnett supplement
Create a visual display of information for an admissions office brochure
Creating Graceful and Effective Visual Displays of Information
Tufte supplements
Discussion of samples
Bring in two examples of visual displays of information,one that is effective and one that needs improvement
Software documentation project,groupwork
Style: Cohesion and Coherence
Lesson Five, p. 88-94
("Beginning a Sentence Well")Complete exercises #1 and #2 in 5.3.
Introduction of Assignment #2, Proposal
March 25
No Class,SPRING BREAK
April 1
Class Topic
Preparation for Class
Due
Week #10
Software documentation project,revise document based on user testing
Memo on results of user testing
Proposals
Woolver, Chapter 11
Andrews supplement
Memo on your proposal topic, who you will interview, and a list of 3-5 interview questions
Interviewing
Memos
Woolever, p. 48-50
Woolever, review p. 141-153
Style: Concision
Lesson Seven, p. 115-123 (through exercise 7.3)
Complete three exercises from 7.1, two from 7.2, and 7.3.
April 8
Class Topic
Preparation for Class
Due
Week #11
Wrap up software documentation project
Software Documentation, Assignment #1
Argument as a rhetorical convention
Woolever, p. 264-265
Re-read your document analysis assignment (from Feb. 11). Bring the graded copy and a clean original.
Peer review of proposal draft (in-class workshop)
Draft of proposal
Technical reports
Woolever, Chapter 10
Review sample reports (TBD)
Introduce Assign. #3, Report
April 15
Class Topic
Preparation for Class
Due
Week #12
Wrap up proposal assignment
Final proposal, Assignment #2
Online Presentation of Information
Web Architecture
Woolever, Chapter 12
Supplemental materials TBD
Analyze a Web site according to the guidelines on p. 362-363 of Woolever
Page Design
Woolever, p. 88-90
Schriver supplement (p. 326-359)
"Page Design" in Intercom, STC, June 2002 (p. 7-9)
Review page layout in sample reports used on April 8
Discussion of samples
Bring in two sample documents: one with an effective page design and one that needs improvement
April 22
Class Topic
Preparation for Class
Due
Week #13
Abstracts and Executive Summaries
Woolever, Chapter 9
Report assignment,Review plan for report and outline executive summary
"Designing a Table of Contents" in Intercom, STC, Nov. 2002 (p. 18-22)
Table of contents and full list of elements for report
Portfolios
In class workshop on portfolio descriptions
Woolever, p. 470-471
"The Ten Commandments of Effective Portfolios" in Intercom, STC, June 2002
(p. 10-12)"Developing a Web-Based Portfolio" in Intercom, STC, Nov. 2002 (p. 4-7)
Draft portfolio descriptions
Web Writing and Web Architecture
Review Woolever, Chapter 12
Supplemental materials TBD
Site map and one page of a Web site created from a print report (TBD)
April 29
Class Topic
Preparation for Class
Due
Week #14
Report assignment,
In-class workshop on executive summary and page layout
Draft executive summary for report assignment
Sample piece of the report showing page layout
Revision of proposal (optional)
Style: Concision
Lesson Seven, p. 123-134 ("Metadiscourse" through
the end)Two exercises from 7.4 and two from 7.5.
May 6
Class Topic
Preparation for Class
Due
Week #15
Report assignment,
In-class workshop on full draft