| This
page contains useful material for teaching a course in software documentation,
both print and online. You may browse the page examining the documents with your browser. To download a file, right-click on it and choose
"Save Target As..."
 This icon indicates that a printable Word file is available.
 Click here to receive a link to the
quizzes page. |
Syllabuses
|
|
Barker's Documentation Course |
Web site for a short-projects course. |
|
Short-Projects
Syllabus |
Short-projects
syllabus, with a blank "date" ready to fill in and adjust, with readings,
quizzes, and exercises. Designed for a 15-week semester.
|
| Assignments for
the short-projects syllabus |
Detailed descriptions of assignments
for the short-projects syllabus. |
|
Supplemental Assignments |
Detailed descriptions of supplemental assignments for the short-project
syllabus.
|
| Semester-long
project syllabus |
Semester-long project
syllabus, with readings, quizzes, and exercises. Designed for a 15-week
semester.
|
| Assignments for
semester-long project syllabus |
Descriptions of assignments
for the semester-long project syllabus.
|
Course
Management
|
| Project
Evaluation Form |
This form shows a generic, fill-in-the-blank evaluation form for small- and medium-sized
projects.
|
| |
Note: The next three
documents comprise a word processing competency test/activity that you can use
to help students develop the formatting skills needed in MS Word to accomplish
the tasks of the course. I usually do this as an un-graded but required
assignment. |
|
Unformatted: Installing Drag And Zip |
This is an unformatted version of the DZ procedure with formatting
instructions in red. Word document format.
|
|
Formatted: Installing Drag And Zip |
This page shows a suggested format for
the DZ procedure. Word document format.
|
|
Word Processing Competence Test |
This score sheet shows all the tasks required to format the DZ procedure.
Word document format.
|
Chapter
1
|
Understanding
Task Orientation
|
| Chapter 1
Guidelines |
Guidelines for a Successful Software
Manual |
| Three
Levels of Task Orientation |
This overhead compares and contrasts the three levels: tutorial, procedural,
and reference. |
Chapter
2
|
Writing
to Teach—Tutorials
|
| Chapter 2
Guidelines |
Guidelines
for Designing Tutorials |
|
Review Sheet for Drafts of
Tutorials |
This form shows evaluation criteria for review
materials and a draft of a tutorial.
|
Chapter
3
|
Writing
to Guide—Procedures
|
| Chapter 3
Guidelines |
Guidelines for Writing Procedures |
Chapter
4
|
Writing
to Support—Reference
|
| Chapter
4 Guidelines |
Guidelines for Writing Designing
Support Documentation |
Chapter 5
|
Analyzing Your Users
|
| Chapter
5 Guidelines |
Guidelines for Conducting a User
Analysis |
| The
Users Learning Curve |
This overhead covers the main characteristics of novices, experienced,
and expert users.
|
Chapter 6
|
Planning
and Writing Your Documents
|
| Chapter
6 Guidelines |
Guidelines for Planning a Documentation
Project |
| The
Documentation Process |
This page lists all 9 steps and
includes a brief description of the activities at each stage. Good overview
material.
|
|
ScopeEstimator.xls |
Scope Estimator. This spreadsheet
calculates total page or help topic count according to graphics, procedure
length, and tables. |
|
PhaseEstimator.xls |
Phase Estimator. This spreadsheet
calculates how long each phase of a documentation project will take. |
| DC_Help.xls |
Dependencies Calculator. A spreadsheet
to adjust page count depending on adverse or favorable project conditions. |
Chapter 7
|
Getting
Useful Reviews
|
| Chapter
7 Guidelines |
Guidelines for Managing Document
Reviews |
|
Review Walkthrough Guidelines |
The review walkthrough is a useful tool
to help students review a document in development, gather reactions to
it, and to articulate progress toward scheduled document goals (communication
and quality-assurance functions).
|
|
Criteria for
Evaluating Review Materials |
Use this when grading review materials for software projects.
It allows you to evaluate how well students conducted their reviews.
|
|
Guidelines For Review Letters |
This overhead is a list of points to remember
when writing good
cover letters. |
Chapter 8
|
Conducting
Usability Tests
|
| Chapter
8 Guidelines |
Guidelines for Testing Documentation |
|
Criteria for
Evaluating Usability Tests for a Tutorial |
Use this form to evaluate test reports for tutorials.
|
|
Criteria for
Evaluating Usability Tests for a User 's Guide |
Use this form to evaluate test reports for user's
guides.
|
Chapter 9
|
Editing
and Fine Tuning
|
| Chapter
9 Guidelines |
Guidelines for Editing Software
Documentation |
Chapter 10
|
Designing
for Task Orientation
|
| Chapter
10 Guidelines |
Guidelines for Designing Documents |
Chapter 11
|
Laying
Out Pages and Screens
|
| Chapter
11 Guidelines |
Guidelines for Designing Pages and Type |
Chapter 12
|
Getting
the Language Right
|
|
Chapter 12 Guidelines |
Guidelines for a User-Oriented Style |
| Answers
to Exercises Chapter 12 |
This page shows answers to
exercises 3-16, Chapter 12, "Getting the Language Right."
|
| Problems of Style in Software Documentation |
This overhead shows the main problems discussed in chapter 12. |
Chapter 13
|
Using
Graphics Effectively
|
| Chapter 13 Guidelines |
Guidelines for Using Graphics
Effectively |
Chapter 14
|
Designing
Indexes
|
| Chapter 14 Guidelines |
Guidelines for Designing Indexes |
