About This Course

 

Table of Contents for this Reading

About This Course. 1

How this Course Differs from Other Writing Courses. 1

It Deals Only with Writing User Documentation. 1

This Course Philosophy is "Do as You Learn"3

What we’re going to do in this Course. 3

We Will Use a Technique Known as Iterative Writing. 3

Our Case Study and Examples. 3

What we will NOT cover in this Course. 3

How to use this Course. 4

 

 

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.

  I use the words “User” and “Reader” interchangeably in this Course.  The “User” is the person using your product and is usually the person reading your User Documentation. 

I also use the words “they” or “them” to mean “he/she.”  For variety I sometimes use “he/she” (and sometimes “she/he.”)

 I also use the word “paper.”  By this I mean any medium that you use to convey the information in your document.  That medium may be print or electronic.  Let’s not split hairs here.

This Course is only about writing User Documentation.  

 

I prefer to not think of this activity as being “Technical Writing.” 

It Deals Only with Writing User Documentation

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 the product.

"User Documentation" is different.  User Documentation is not about the product.  It is about the User's interaction with the product.  It should not be written from a product point of view.  Instead it should be written from a User’s point of view.

What does “User’s point of view” mean?  It means that we will concern ourselves with the tasks that a User might

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.

Having said that, I must add that the User Document should describe (somewhere) how to use all of the controls and features of the product.  The developer of the product expects that everything about the product will be described somewhere.  That somewhere may be the document you are writing or it may be supplementary documentation.

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.

This Course Philosophy is "Do as You Learn"

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:

O     Managing a Writing Team
However, I will present some of the unique needs in managing a writing project.  I shall not go into much detail in this area.

O     Time and Resource Planning of the writing project
I shall suggest when you can do the planning of the writing project (it follows the steps where we describe the product, describe the User , and specify the goals of the document.)
I will present some other document management guidelines later.   In general, I suggest that you must manage the documentation project as you would any creative (development) project. 

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 material.

The old computer saying "Garbage in -- Garbage out" is very applicable here.  Our goal is to ensure that you are not creating garbage wrapped in a fancy technology…that's still garbage. 

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

O     Writing Your User  Document
You actually do the writing as you work on each Step

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?          

___True      ___True

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.

 

 


Resources for Writing Great User Documents: Home

(c) 2006 Igetitnow! Training, Inc.