Technical Writing Tips

[Douglas Max <dmax -at- BELLATLANTIC -dot- NET>]

Don't have the extra lines to explain...here are the unformatted tips
I've received.  Formatted coming...when I get the time. Send personal
e-mail to me for attachment in Word. Doug
Technical Writing Tips


 * Learn to bake fudge or brownies -- they get your foot in the door
with most SMEs
 *Look for the "obvious question" with a not so obvious answer
 *Remember that when the document works transparently (the user gets the
information without
    being quite aware of using the documentation) you win!

Writing User Manuals/Writing Software Documentation
*       Know your audience
*       Don't think of what you're writing as "technical" documentation
as you write it
*       Use a graphic to nail down the idea

Titles, Headings, Captions
*       Use action headings (i,e; Instead of "The Add Feature", use
"Adding a Thingamabob"
*       Make the headings interesting to grab the use

How about "brevity in writing".  If you can say something in 5 words,
great,
don't explode it into 10.  In other words, KISS (Keep It Simple Stupid)
the writing.

Examples, examples, examples.

As you write, concentrate on making the technical material
NON-technical.Think of yourself as the user. Pretend you don't know
anything about the material and write as you would want to read. As you
write, consider each word carefully, especially verbs. Think to
yourself... "What does this word connote
(What picture do I see when I read this word)?" What you may see, isn't
necessarily what the user sees.


Passive Voice:  When the receiver of the action becomes the subject of
the
sentence, and the doer (if even mentioned) appears after a "by" phrase.

Many are often too busy slamming passive voice, but many miss the fact
that
passive voice does in fact serve a purpose (sometimes). Consider the
following:

Use passive voice:

To focus attention on the action rather than on the doer of the action
."Our car was stolen."

To emphasize the receiver of the action
"Many natives are forced to leave their beautiful beaches to make room
for condominiums."

When the doer of the action is unknown or unimportant :"An error has
been made."

I suggest that we say, "Avoid needless use of passive voice." I, for
one, try to avoid the passive whenever possible. I'm by no means
condoning the use of passive voice. We just need to understand that
passive voice does have a place in grammar.

o  Not only avoid the needless passive voice, avoid needless
nominalizations.A nominalization is a verb or adjective used as a noun.
These tend to make nouny sentences. It might seem difficult to find the
happy medium between no passive and no nominalizations, but it's there.
install (verb)    installation (noun)    precise  (adj)   precision
(noun)

Which of the following implies action: This is a description of the
software installation.
This describes how to install the software.

Topics/Procedures:

o  Use one main idea per topic.
o  Use action verbs in the beginning of steps, unless a road map is
important.
o  Get the subject of your sentence within the first 6 words. Users
don't want wordy sentences, they want help.
o  When is the last time you sat by the fire to read a nice user manual?
Users read a user manuals when they are stuck. The stop reading manuals
when they get un-stuck. Remember this when mapping your info.
o  How do you get 1,000 different people to see things your way? Tell
them what to expect, then tell them. Use "forecasting statements" and
conventions sections to explain your manuals. Explain the manual before
you explain the product.
o  Use short sentences and short paragraphs.
o  Capture illustrations at the highest quality, it's much easier to
down sample.

Consider a High Impact approach to document reviews.

High Impact Review:  Each reviewer gets a copy of a manual to mark up
within a specified time. A reviewer sign-off sheet accompanies each
reviewer's copy. All reviewers meet at a specified time/place to discuss
their comments and markups, page by page. The tech writer mediates the
meeting, collating all comments onto one master markup. Reviewers
relinquish their review copies to the tech writer at the end of the
meeting.
Pros: Reduces the number of reviews required for new-product
documentation. Group meeting after initial, individual review encourages
each reviewer to actually review the manual. Anyone who has not
completed their review is not allowed to attend the group-review meeting
(these people stand out before
long). Conflicting comments, opinions, and markups are resolved
instantly. Everyone knows what each other commented. Helps SMEs resolve
product-related issues. Reveals weaknesses in processes, product design,
team communications, etc. Among product-design team members, clarifies
product-related
misunderstandings that may otherwise have gone unnoticed without group
discussion. Too many other advantages to list here.
Cons:Greater paper consumption than a serial or collated review. People
not accustomed to this review process may resist the process change.
Difficult to get all reviewers to meet at the same time, and for two or
four hours.

I suggest providing snacks to help bribe the SMEs to joining the review.
Not so much getting them on your side, but bribing them to attend.

Dealing with SMEs: o  Be as prepared as possible before going to the SME
for information.
Anticipate as many questions as possible.
o  The better your work, and the more organized your approach, the
better your relationship will be with SMEs.
Headings & Captions:This topic is too deeply rooted in personal style to
come up with any explicit
tips, but a few obvious things to remember are:
o  Plan out your heading hierarchy when you outline your document.
o  Make your headings as intuitive as possible.
o  Keep the headings short, but informative.
o  Consider using a san serifed font.

o  Always consider cross platform compatibility.o  A picture is worth a
1,000 words... only if it replaces 1,000 words. Too many illustrations
can destroy usability.
o  Review your grammar every few months.
o  Join the STC.
o  Consider using PDF.
o  Dictionary = GOOD; Thesaurus = BAD (unless you completely understand
the
word you are using to replace another)
o  What one person says is right, isn't necessarily right or wrong. When
it's
a question of style, there are as many opinions as tech writers. Pick
what
works for you and your users, but remain consistent. For example: I
could be
100% wrong.

Keep toys at your desk for SMEs to play with.  While they are engrossed
with the Silly Putty or Legos, ask your questions.

The acid test for me has been "Could my Mom read this and be able to
follow it?"  Not make it speak down to anyone, just explain it to the
point that an intelligent outsider could follow it.  I've never actually
asked her to read anything (confidentiality) but I've imagined her as an
end user.  Works.

Use everything and anything you can find to get information for your
document.Pick up a speck or the code, even if you think it is beyond
you. You might be surprised how, with familiarity, it all starts making
sense.

Learn how to communicate with each individual SME. Try different ways,
some will open up on the phone where they would not in person. Some will
write a book for you on email and barely speak to you in person. Each
communicates differently. And remember, communication is our field,
SME's often find it
difficult. Patience is a requirement. Also, learning to ask the right
question is vital. The only way to find out how to do this is to keep
experimenting until you figure out what works.

Avoid the passive voice (when appropriate) and first person pronouns by
using the imperative voice.

Always use parallel construction of terms throughout the document. If
you called something a whatzit in the beginning section, don't call it a
thingamajig later on.

If you are writing a document, create the index tags while you are
writing. You know what you are writing about now. You may not remember
at iterations of the topic later or you won't have time to
go back and create the tags later because of deadline considerations.

Don't try to edit at the same time as you are writing. Write now and
edit later lest you get bogged down in details over one item and forget
the line of thought you were following.

Graphics should follow, as closely as possible and never more than one
page away, or the reader will tend to get lost or ignore the references
because by the time they find them they forget what detail
it is they are looking for.

-Bring a breadmaker machine to work and make bread.This woman swore this
was the ultimate way into the hearts of programmers. Also it would help
when you need to get to someone who may be very hard to get hold of.

Never use a noun as a verb. (I'm going to transition to marketing.)
Never use a verb as a noun. (John is going to do an install.)
Never use a slash to replace "and," "or," or a hyphen.
Write to the fourth grade reading level. Even a rocket scientist can
understand it.

Think Of The Reader

If more than one tech writer:
*       Use peer editing
*       Hold regular meetings to discuss new ideas, ways to improve the
documentation
*       Develop and use a style guide


I've found it can be hard to get people to give me information in the
first place, but they are eager to tell you what you did wrong. So
sometimes I just guess and let people correct me. I mark the guesses
with a different background color, to keep the real facts separate from
the guesses.

"Do you *really* want me to make this up out of my twisted imagination?"
is a very effective threat for some of us. I once wrote a few pages of a
manual for an OS that would run on any hardware at all including a
brick. I particularly liked the Open Window Permanently command.

Keep a whiteboard for the tech writing department with a bulleted list
of information planned for
releases.  As SME's pass, they will see it and often volunteer
information to be included.  Make it clear that the white board is open
for any information anyone thinks is needed in the manual.


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=