There is no recipe to tell you exactly what specific documentation deliverable
should be made up of.
But it's a good idea to start out by defining a few
types of documentation deliverables and built around them.
You can make your life easier by making decisions about what type of information
go into what document.
Then, avoid copying information from one document into another.
Tempting as it may be, to assist your user by including key information
in every place, in every section, where you think it can be helpful,
it can cause problems with maintenance and consistency.
It's a sure thing that you'll update information in one place, but not another.
It is embarrassing when you discover that one of your documents contains
outdated information while it's correct in another.
No matter what your final output,
this is a good time to start thinking about the fact that you will probably plan
to use a great deal of your content in multiple output forms.
Single-sourcing refers to the development of content with the intent
of producing all of the parts of the document in multiple formats,
instead of copying content into different files and formats, and
maintaining it in more than one place.
The content exists in one place only.
Typically, this means that you have many files stored in one location,
and you use all of them in each individual deliverable.
Content reuse refers to the management of content by breaking it into small enough
components or topics so that each topic can be used in the appropriate place.
Topic-oriented writing is writing that is intended for use.
Each topic is a unit of information that stands out and
can be mixed out and matched with other units.
If you're accustomed to writing in a linear narrative style,
topic oriented writing may require some effort to learn.
Single-sourcing can be as simple as creating a single file
of content that you'll then generate for print PDF or HTML.
Or it can involve the creation of many small modular topics and conditional
content files that a tag mix and match to build different types of output.
In all cases, changes are made only to one file, the source file.
For example, the help and user guide for
an application are likely to share most of the content.
In fact, if you are creating a user guide, online help, a data sheet, and help for
a mobile device for the same product, they are very likely to share some content.
There are many decisions to make about how you present the documentation content.
These decisions depend on what your users need to know, and
how they will use the documentation.
It may also be based on how much time you have to work on the project and
how many different deliverables are produced from the same content.
In addition to those decisions, you need to decide
whether your documentation is task-based or reference-based.
Choosing one of these forms depends not only on what the user needs,
but also on how much time you have to work on the project, and
how much content we use is involved?
Task-based documentation is about what the user does, with
instructions on how to operate the product to accomplish the task the user performs.
This could involve moving back and
forth between different screens, different manuals, and perhaps,
combining a number of shorter processes to accomplish the goal.
Elena BazanovaDirector of the Language Training and Testing Center
