|
|
 |
The
Keys to Clarity, Consistency, and Correctness
By Rives
Hassell-Corbiell
How
can you make documentation more clear, consistent, and correct for
your users? Following are some guidelines I find effective when
documenting concepts and organizing documents.
Documenting
Concepts
|
Consistency
To
provide consistency when documenting a concept:
-
Use
the concept in one context.
-
If
you must change contexts, alert your audience and tell them
how the new context differs.
-
Use
navigation, formatting, and graphics that facilitate
understanding of the concept.
|
|
|
Clarity
To
provide clarity when documenting a concept:
-
Present
new information by leading from the familiar to the unfamiliar,
using examples or analogies.
-
Use
familiar language, define new terms, and use the terms in
consistent contexts.
-
Avoid
cleverness, insider humor, and abstract explanations.
Correctness
To
provide appropriate focus and scope when documenting a concept:
-
Ask
what about the concept is important to the audience. Why should it
interest them? How does it apply to them?
-
Attract
and keep their attention by providing examples and applications of
the concept that are useful to them.
Tools
What
I consider the most important tool for effective application of the
3Cs to documenting concepts is substantive editing for style, tone,
structure, logic, and accuracy. This might require reorganizing the
content, changing headings, rewriting text, eliminating wordiness,
inserting transitions and summaries, resolving inconsistencies, or
clarifying confusing sentences or paragraphs.
Organizing Documents
Consistency
-
Create
predictability and comfort for the user by standardizing your
document format, text formatting, and your use of icons.
Consistent organization provides landmarks—it helps orient the
user and removes barriers to learning.
-
Consistent
organization that helps the user is like a boat afloat on the
surface of clear seawater—the support is substantive but
transparent.
Clarity
-
Use
headers and footers that inform and orient the user. For example,
training course instructor guides can be hundreds of pages long.
Headers can include the course section and lesson names. The
footer can include the course name, copyright holder and date,
page number, and sometimes the version or date of issue.
-
Intuitive
navigation, colors, fonts, and blocks of content that require no
side-scrolling are key to web site clarity.
-
Use
transitions that review what you covered, how that relates to what
you are going to cover, present the new material, then review why
it was important.
-
Chunk
the content into bite sized pieces for the user.
-
Organize
the content in the way the user needs it. For example, ineffective
software user documents are often organized into sections that
correspond to menus, and chapters within the sections that
correspond to features on that menu, without regard for orienting
the user to what the software is for and how they can apply it to
solve problems. Effective software user guides organize by how the
user needs to understand and use the software: what is it for,
what can it do for them, and steps for performing key tasks.
Correctness
-
Identify
and adhere to the scope and focus of the document.
-
Remove
historical, nice to know, and other sources of interference to the
focus and scope of the document. If you realize some content is
extraneous but you must include it, put it into an appendix,
footnote, or sidebar.
Tools
-
Use
a style guide. Use an appropriate one for your locale and
industry. For this article I used The Chicago Manual of Style.
Additionally, develop a style guide for each project, which
includes jargon, acronyms, and occasional unconventional
formatting requirements. This is of value even if you are a
development team of one. Once a document grows past 100 pages in
size, or two revisions, your memory will be challenged to recall
the decisions you made.
-
Use
a follow-up checklist to ensure that you have consistently applied
spelling, grammar, structure, navigation, and other guidelines to
items that changed during the development process, for example,
department and product names, and to ensure that you include
updates or tweaks to documents you repurpose.
-
Use
templates to ensure organization consistency and save your focus
for content design and development.
These
are a few guidelines that have helped me make documentation more
effective, and it is my sincere hope that they will help you.
Example
of a table that provides conceptual clarity by comparing what is
familiar to what is unfamiliar. Parallel formatting of content on the
left and right sides is an organization technique that provides
consistency.
| Documentation |
Training |
| Is an information
product |
Enables through
experiences |
| Increases
understanding |
Develops skills
and knowledge |
| Focuses on a task:
how to get from A to Z |
Focuses on job
performance: learning what to do and how to do it |
| Is organized for
information retrieval |
Is organized for
behavior change |
| Scope: one task
broken into steps |
Scope: collection
of skills and knowledge required to perform a job |
| Customers are
called users |
Customers are
called learners |
[Example of a table
that provides conceptual clarity by comparing what is familiar to
what is unfamiliar. Parallel formatting of content on the left and
right sides is an organization technique that provides consistency.]
Rives
Hassell-Corbiell is an educator,
consultant, and the author of Developing Training Courses: A
Technical Writer’s Guide to Instructional Design and Development.
Rives owns The Learning Edge, an international consulting firm in
Tacoma, Washington, USA. You can contact Rives at riveshc@lepublishing.com.
STC
India | Home | Contact
Us
Copyright © 2002 India Chapter
STC.
All rights reserved.
|
|
READABILITY
