|
| |
Please
select a technical writing service to view details.
The
quality of your product's online help can influence your product's
reputation. End users become frustrated if they cannot find information
they need. They typically search by task at the time they are trying to
accomplish that task. Context sensitive help will bring
up the most relevant help topic based on what the user is doing at the
time. Truly
brilliant online help is the result of extensive usability testing and contains
a troubleshooting section, lots of helpful hints, significant
cross references to other relevant topics, and a comprehensive index.
It can even contain paths where the user is lead
from one task to the next logical task, not
unlike an online tutorial. Training
tutorials can range from comprehensive instruction
in the use of
your entire software product to a clarification
of just the
more complicated tasks. Offering training
tutorials on your product's web site or in
conjunction with online help can significantly
reduce the number of calls to your technical
support staff. The key is to
think like potential users. Determine how the
end user will use your product, include
information to answer their questions at an
appropriate level of detail, and make the
information easy to find. Online help is not merely a listing of all of the software's features and how to
access them - that would be a reference manual.
User
manuals are all about the user. The easier to understand and the more
relevant to how the user will really use your product, the better. That is
why I favor preliminary audience analysis and a task oriented approach to user
manuals. About
style guides: A
style guide ensures consistent documentation across an entity. In other
words, your documentation either reflects well or poorly on your company. Style
guides encompass the physical layout of documents (page headers and footers,
copyright statements, table of contents, size of screen captures, index, and the
like), usage (abbreviations, use of capitalization and boldface type), and
standard wording such as using "press Enter", not "press the Enter
key." Even the decision about how references to the Enter key appear
in your documentation is specified (ENTER, <ENTER>, Enter, or Enter) - the
choice is not as important as consistently using the same wording and format.
The
better online help systems can substitute for training materials, especially
when they are task oriented and contain learning
paths. But proper training materials are required
for classroom training, online training, or tutorials. A thorough understanding of your product,
how it will be used, adult learning methods, Bloom's
taxonomy, and real world, relevant training
exercises all increase the likelihood that end
users will truly learn something from their
training. The
most common errors I see are failure of the course to cover all of the stated
objectives, improperly worded quiz questions or questions that were not
addressed in the course material, and too much use of passive voice.
When
developing training for adults, keep in mind these adult learning principles.
 |
Focus
on "real world" problems.
|
|
Emphasize
how the learning can be applied.
|
|
Relate
the learning to the learners' goals.
|
|
Relate
the materials to the learners' past
experiences.
|
|
Allow
debate, challenge and the exchange of ideas.
|
|
Listen
to and respect the opinions of the learners.
|
|
Encourage
learners to be resources to you and to each
other.
|
|
Treat
learners like adults.
|
|
Give
learners control.
|
Technical
editing is much more than checking for misspelled words and proper comma
use. It is ultimately quality control. Technical
editing considers a document's intended use,
organization, design, and style, along with an
analysis of the content. While rules-based
copy-editing is included, a substantive edit is
designed to make the document not only correct, but also functional for the
intended
readers. Basic
edit - catches the most obvious and basic errors
|
|
Read
the document word-for-word. |
|
|
Edit
the document at the sentence
level for grammar, punctuation, spelling, and
consistent use of formatting styles. |
|
|
Check
front matter for appropriate information. |
Intermediate
edit - basic edit plus a consistency and accuracy check
|
|
Check
language and usage for clarity, consistency, accuracy, passive vs. active voice,
eliminating run-on sentences, wordiness,
gender-specific language, awkward
constructions, and vague language. |
|
|
Edit
the document at the paragraph
level for tense consistency, coherence, and transitions. |
|
|
Check
the integrity of the document to ensure references to figures and tables,
headers, footers, screen captures, and table of contents
are accurate, complete, and consistent. |
|
|
Insert
comments or questions regarding items such
as misused words, inappropriate content or
tone, missing cross-references, major
organizational problems, and awkward or
confusing passages. |
|
|
Ensure
all steps are numbered sequentially. |
Substantive
edit - intermediate edit plus a complete analysis of the
document
|
|
Review
and comment on the logical
organization of the document. |
|
|
Check
software against instructions
to ensure instructions are clear and complete
if necessary. |
|
|
Check
screen captures for accuracy and
appropriateness. |
|
|
Refine
the document's language, making suggestions
to improve the clarity and quality of the
language. |
|
|
Determine
if the document is appropriate for the
target audience and is written at the
correct readability level (Flesch-Kincaid). |
|
|
Ensure
document-wide adherence to formatting and use of styles. |
|
|
Check
the index for completeness, consistency, and accuracy. |
|
|
Check
for omitted topics and
redundancy. |
|
|
If
the document contains hyperlinks, ensure
none are broken. |
Proofreading
is also a detailed task, but a simpler one concentrating more on comparing the last draft of a
document to a new draft to ensure all marked
changes are made, or in the case of retyping a document, ensuring that the new document matches the original.
|
