0:00
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.
4:00
As you develop task-based documentation, make sure
that you clearly define the starting and the stopping points for each task.
In other words, what is the first step the user does to start the procedure,
and what is the final step that indicates success?
Use a consistent format to present each task, a description of the task, and
its purpose, a lead-in heading, and a set of numbered steps are typical.
As you write these tasks, you may realize that the software and
hardware has functionality and features that you never mentioned at all.
4:38
Many products have a lot more features than are commonly used.
Think of how many things your phone and
camera can do that you have never even tried yourself.
Some products have legacy functionality that isn't used in any workflow.
Those little used functions can be saved for a reference manual, or
a more detailed version of the user guide.
You will have to document them somewhere because customers of older versions,
who use those functions will want to know where they are in this version.
In the reference-based approach, the focus is on, what the product does,
what does it look like, what does each menu, item, and button do?
What information goes into a text field?
It's up to the users to decide how to put all these components together
to accomplish their goals.
Because of that, it's not always the right way to provide user information.
6:07
It also takes less time to develop than task-based documentation,
because there is less thinking and planning.
When you're short on time, and
you have the budget to produce only a single piece of documentation for
your product, you may choose to provide reference-based user documentation.
You can plan to go back later and expand it to a task-based approach.
To create reference-based user documentation,
go through the application's or device's user interface, and
describe each single component accurately and consistently.
Scenario-based information is information that is designed and
written to support user's progress through scenarios to achieve goals.
When you write scenario-based information instead of thinking of a scenario
as one topic that you write, you think of a scenario as the basis for
everything you write.
You identify the key goals for users of the product and then for
each goal and create a scenario, or path, or how users will accomplish the goal.
Elena BazanovaDirector of the Language Training and Testing Center
