|
| |
Please
select a technical writing service for 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.
Back
in the day when I worked in someone else's office, I always wrote procedures
for every task for which I was responsible. My motives were initially selfish - I
was learning new tasks and only wanted to ask how
to do them once so I would not appear stupid to
my boss, hence the need for notes and
ultimately, desk procedures. Interestingly,
the procedures increased
efficiency by aiding in cross training, new employee training, and by helping
with SOX compliance (documentation of internal controls).
Proper
procedures allow anyone to do a job by following clearly
written steps. Most often, what is missing from procedures is tangential
but equally important information such as where to file copies, who
needs to sign forms, or what to do in case of error. These details
can make or break office procedures.
Franchise
operations manuals are a combination office
procedure manual/personnel manual/and reference
guide containing all forms used by the business.
I develop franchise operations manuals using a
very detailed outline as a guide. You select
what items you want to include in your manual
and you receive your manual as a Word document
so you can keep it up-to-date. It's a highly
collaborative and rewarding joint effort.
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 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.
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.
|
Administrator
and Installation guides focus on the technical aspects of the software rather
than the use of the software. Subject matter experts are key for useful guides
as are clear step by step instructions, thorough documentation of the
application, and a comprehensive troubleshooting section born of thorough
testing.
Software
documentation is what you wish your programmer had time to
do while coding. You need someone to pull the
information out of the programmer's mind and put
it in an easy to understand format. The target audience is not end users, but programmers. It is a reference manual that contains the programming elements, data
dictionaries, entity relationship diagrams, and other "computer
geek" information so that if your programmer gets hit by a bus,
another programmer can come up to speed quickly. If you are a public
company and need to comply with SOX, this is especially helpful as an internal
control document. About
data dictionaries: Don't
you just hate it when you look at a data dictionary and the description of the
field name is just a repeat of the field name? That's not
helpful. I
work with programmers, end users, and database administrators to capture the
following information about each field:
|
helpful definition and purpose of field |
|
field type (numeric, date, string, etc.) |
|
field length |
|
field required (Y/N) |
|
format - currency, blank when zero, etc. |
|
acceptable values for the field (such as codes and what each code means, and if
the field |
is a lookup field, the name of the table supplying the values)
|
null allowed (Y/N) |
|
note if field is a key field (primary or foreign) |
|
data processing requirements (does the program code validate the values entered
into the field) |
|
notes (programmer notes)
|
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 functional for its
readers, not just to make it correct. I
use the following levels of edit: 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-n 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
concentrates 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.
Most people scan web
pages rather than read them word-for-word, thus it is important to use words
sparingly and wisely. Structure web pages accordingly by using shorter
sentences, bulleted lists, hyperlinks to additional information, more white space on the page, and
short paragraphs that address a single topic. Also avoid hyperbole - people are desensitized to and
distracted by such phrases as "the best," "greatest value for
your money," and other such promotional language. I
generally use my
finance, budgeting, and accounting background to write about business topics,
although I am comfortable researching and writing about a variety of topics.
I
believe a good technical writer will perform usability testing as a matter of
course when documenting software. Much more than just checking for bugs,
usability testing determines what works well and what does
not, from the end user's point of view. The main goal
is assurance that your product is intuitive and enables the end user to become
productive quickly. The earlier in the development cycle that usability
testing can begin the better, because it is easier for your programmers
or web site gurus to incorporate changes in the beginning than at the last
minute.
As I was creating online help from a user manual created in
FrameMaker, I noticed a few things in the manual
such as the step numbering being out of sequence, a few
typos, a few incorrect directions, and a screen
capture that did not match the directions. I alerted my client
and the user manual was corrected.
I worked on a context sensitive help project where the
programmer had never called context sensitive help from a program. I sent him
some code to use and helped him through the process.
I care about your entire project, not just my piece of
it.
|
