In this Course you’ll learn to create great User Documentation. And we can make creating it easy enough so that it practically writes itself. And fun, too.
Wording in this Course.
This Course is only about writing User Documentation.
I prefer to not think of this activity as being “Technical Writing.”
Most “Writing Courses” are general writing Courses. This Course specializes in “Writing User Documentation.” I don't like the term "technical writing," so I rarely use it.
My problem with the term "technical writing"
is that it can lead the writer to writing from a product point of
view. That is, the "technical
writer" might base his/her documentation on the controls and features of
O want to do,
O need to do or
O be interested in doing
with the product.
It means that we will not assume that everything about
the product is perfect (I rarely found one that was). Instead we will be concerned that things
can go wrong (they do not do what the User wants or expects), and that we
should add material to our User Document to both identify the imperfect
situations and how the User can get beyond them.
Someone once described Technical Writing as “getting what’s in my head into your head.” To me, User Documentation deals with “helping the User get his/her tasks completed with the product."
Essentially, many of the decisions about writing such as
O Style to choose
O How to develop arguments
O Coming up with ideas (fictional work)
are already made. By limiting the topic to “User Documentation” many of the concepts that you learn about in a “writing Course” are unnecessary. For example when writing User Documentation you need not worry about character and plot development.
Most writing Courses and books stress grammar. In this Course we do not! We shall leave perfecting the grammar to the grammarians: our proofReader/editor. (However I will discuss one point of grammar later. I only present that point of grammar to enhance the clarity of your writing.)
So we have selected a style based on the topic (User Documentation, not a novel, not a philosophical disCourse), we will learn how to generate the topics, organize, and write them. And we’ll do amazing things to make your User Documentation a useful support tool for your product.
And we can even go one step further in this difference between User Documentation and other types of writing. Most writing is meant to be read from start to finish. User Documentation is rarely read that way. Instead a User reads only the pieces of the Document that he/she hopes will solve their problems. As a result we can relax the general guideline that writing must be of a consistent style throughout the Document. It must be good writing, but the style doesn’t have to be 100% consistent.
In other Courses you go off and study and learn, and then return to your work and try to use what you have learned in order to accomplish your task.
In this Course, you actually do your real-life writing as you progress through the Course. This Course guides you in your creation of great User Documentation.
Learn how to write documentation. You will actually write the documentation you need to write for your work. You can’t beat that for a great goal!
Little grammar! Except for one topic, pronouns, we are not going to cover the rules of grammar in this Course. Your editor will enforce the rules of grammar – to the extent that the rules support document clarity.
Essentially Iterative Writing involves dividing the User Document into chunks that we will call “Components.” As we complete the draft and revision of a Component, we will internally publish the Component for our Components Readers to comment on. The Components Readers may be the other members of the Product Team (those working on the product) and anyone else within the organization who has an interest in the product.
We will evaluate their suggestions and comments about the Component, and incorporate the ones we “like” into the next revision of the Component.
This Course is a “hands-on” Course because you will be creating the documentation you have to do for your real-life work. We’ll follow a series of steps that will take us from the start to the completion of your real-life writing project. If you have a writing project for your work, then that will become your Course Case Study.
If you do not have a writing project for your work, then you will create your own Case Study. You will select a product in your life and create great documentation for it. You will compare your documentation to the documentation that came with the product. I expect that your documentation will be much better than that which came with the product.
Throughout the Course there are examples of good and bad User Documentation taken from the real world. The fictitious Acme International Products Corporation, called "Acme" in this Course, created all the products described in this Course. I have also included examples based on the User Documentation of a fictitious word processor, called WordWhacker.
The following topics are not part of this Course:
Managing a Writing Team
Time and Resource Planning of the writing
O Grammar: Except for only one point of grammar (pronouns) we shall leave points of grammar to the editor that you get to review your work.
O How to use any particular piece of software. My goal is to tell you what and how to write, not what to click on a piece of software.
O Any emphasis on technology.
This Course deals with communicating information to human beings. Whether that information is published in XML or an online help system, or popups (info pops), or printed manuals, the technology is secondary. The information, its order and accessibility are our main goals.
No matter what fancy electronic presentation tool you
use, if the material is no good, then the presentation is no good. In this Course we will concentrate on the
This is a Course on writing great User Documentation. We strive for clear, effective writing and documentation that will be most effective for the majority (hopefully all) of your Readers.
“Read the entire Course before actually going through the material in depth.”
Now I believe in “reality” and reality says that very few people do this. Your User Documentation might ask the Reader to read the document through before using the product. Nobody does that either. So don’t expect them to do it. I don’t expect you to do this. So here’s a brief overview of the material in this Course:
O “What is great User Documentation”
O About “Reality”
O Things to think about and considerations “before you write”
O Getting Resources
O Gathering Information
O Your writing tools
O Generating Topics for Your User document
Writing Your User
O Improving the Access to the Information in the User Document
I do strongly suggest that you read each Section of the Course before you work on the activities of that Section.
There are no cute little (and usually insulting) quizzes in this Course. You will be doing hands-on assignments, and more importantly, you will be creating your documentation as you progress through this Course.
True or True: This is the only quiz in this Course?
This is a Course without lessons. If you wish, you can consider each topic in this Course a lesson. I found writing the word “Lesson” all over the place to be more of a distraction than a benefit. In either case, if you follow along and do the work, your writing will be progressing in a great direction.
(c) 2006 Igetitnow! Training, Inc.