Course Name

Writing User Guides

Contact Hours: 24

Course Description

Designed for people who want to enter the technical writing field, this course focuses on writing effective user (how-to) guides and gives an introduction to the job of a user guide writer.   Whether writing for the users of a company’s computer system, for cashiers who need to know how to use a scanner, or for owners of a new appliance, user guide writers are needed. And, writing for the end user is one way to enter the technical writing field. Many writers start their jobs at companies maintaining and creating end user materials.   Coursework focuses on how to write reader-friendly documentation, what to look for in maintaining existing guides, the steps involved in creating new guides, working with style considerations, the differences between editing and proofreading, and the job of the user guide writer. Students will get the opportunity to write several end user pieces. The first four weeks of the class introduce students to the how-to of writing user guides and give an over of this aspect of the technical writing field. The last four weeks of the class will act as a workshop. While additional topics will be discussed, the focus is on writing a major assignment. With instructor guidance, students will hone their projects. The goal of the assignment is to create a sample piece for the student’s portfolio.

Outcome

Students are assessed by: By making updates to the pages of a fictitious user guide based on a mock source document. By writing a short how-to section on using a grocery store scanner. By completing a proofreading exercise and a writing exercise By creating a mini-user guide detailing an e-mail system By creating a style-sheet

Assessment

After taking this course, students will: Understand what is involved in doing the job of a technical (user guide) writer Be able to create reader-friendly documentation Have a sample “how to” piece to add to their portfolio Have a basic understanding of the field of technical writing Know the difference between proofreading and editing and be able to apply these skills to their work

Outline

Week 1: Introduction In the first week, we will take a brief look at the field of technical writing and some trends in writing user guides. Students will become familiar with how the job of a user guide writer is structured. Also, we’ll look at a few pages from a paper-based guide and then talk about electronic publishing. Students will be asked to write directions for a common task as a “warm-up” exercise. Also, they will be asked to tell a little bit about themselves and why they took this course. Week 2: The Mechanics of Creating and Maintaining User Guides In this week, we’ll take a top to bottom look at the mechanics of creating and maintaining a guide. We’ll start by looking at the lifecycle of a guide (birth, maintenance, resurrection, death). We’ll follow that by talking about what it takes to go from blank page to distribution, the procedures involved in getting a writing assignment in the lifecycle out the door to the user. We’ll end by looking at elements involved in researching and writing text. We’ll talk about working with source documents. Students will be introduced to the “3 C’s” of good technical writing: Clear, Concise, and Complete. For many writers, their first job assignment is to do an update (maintenance) to an existing manual. In this week’s homework, students get a chance to do a maintenance assignment. Students will be given a mock specification memo (source document) pertaining to updates to be made to a fictitious user guide. They will also receive pages of the fictitious guide. It will be the students' job to determine from the memo what needs to be changed within the guide pages and make those updates. In addition, students will be asked to observe cashiers using a scanner in a grocery store (use the self-service lane, if available in their area) as part of their research for the week three assignment. Week 3: Steps in the Writing Process When creating a brand new user guide, a writer doesn’t just sit down and start describing how to use a product. There’s a lot of upfront work to do first. This week we focus on writing from scratch. We’ll start our scenario at the very beginning: being assigned the writing project. From there we’ll take a look at the steps needed to come up with the finished text. We’ll discuss: gathering information (on the audience, medium to be used, etc.), planning the document (style/format, etc.) outlining, drafting, testing, revising, and editing. Students will complete a small case study, The Fairfield Scanner, for which they will write a two-three-page user guide section. Week 4: Opportunities and Resources for User Guide Writers Before going on to the workshop component of this course, we’ll use this week to review any questions on the previous weeks’ material, look at the types of job opportunities available to user guide writers, and talk about some resources available to them. User guide writers may work as either employees or consultants. It used to be that writers who worked as employees of a firm felt that consultants had the better deal, “the greener pasture”. However, the differences that used to exist between employees and consultants are disappearing with time and the market place.   There are pros and cons to each position and we’ll discuss what those are. There are a variety of resources available to the technical writer. I’ll share some websites of interest and talk a bit about the Society for Technical Communication. Students will be asked to send in questions regarding the material presented in the first three weeks of the course and the technical writing field. From that, class Q and A feedback will be created and shared with all students. Week 5: The Case Study Begins (Considering Layout and Design) During the last four weeks of the class, students will put together a short user guide sample describing how to do certain e-mail functions. The students will use their own e-mail systems as the basis for this project. This week, we'll talk briefly about some things to consider when creating the layout of a guide. This will include talking about using screen prints (for those guides that need to use them). Students will write a user guide section describing how to sign on to an e-mail system and access mail. Week 6: Editing, Proofreading, Style- sheets, and Proprietary Information Many times a writer must be an editor and a proofreader, too. We’ll look at editing and proofreading and how they differ. We’ll cover creating style-sheets as a map for consistency. In addition, we cover the subject of proprietary information. Unlike other types of writing (like magazine or newspaper articles), the technical writer does not own the rights to the user guide he/she creates. We’ll talk about what that means to the writer. For this week, students will be asked to createa style-sheet for the guide section written during week five. Also, there will be a proofreading exercise to complete. Week 7: Consistency Students will write two more guide sections: how to read and save incoming mail and how to send a note. Utilizing their style-sheets, student should strive to make sure that the new sections have the same tone and look of the sections assigned in week 5. In addition, students will revise and resubmit the previously written sections (signing on and accessing mail) based on the instructor feedback they have received. Week 8: Polishing the Piece: Having received instructor feedback on the previous assignment, students will make any revisions needed. In addition, they will create a table of contents, a systems message log in which they will describe error messages and their resolutions, and a glossary.ide section written during week five. Also, there will be a proofreading exercise to complete. Week 7: Consistency Students will write two more guide sections: how to read and save incoming mail and how to send a note. Utilizing their style-sheets, student should strive to make sure that the new sections have the same tone and look of the sections assigned in week 5. In addition, students will revise and resubmit the previously written sections (signing on and accessing mail) based on the instructor feedback they have received. Week 8: Polishing the Piece: Having received instructor feedback on the previous assignment, students will make any revisions needed. In addition, they will create a table of contents, a systems message log in which they will describe error messages and their resolutions, and a glossary.