Best practices in Technical Writing by Atinder Sodhi in the TWB Alumni knowledge sharing session.

1. By: Atinder Sodhi

2. Technical writing is writing on a specific subject for a
specific purpose to a specific audience.
Technical writers can be considered as a bridge
between people who know technology and people who
use it.
They understand the complications of technology and
put it in simple words that help the user understand and
use the technology.
 User Manuals, Online help
files, Reports, Proposals, Procedures, Release notes
, Brochures, etc.

3. Audience analysis is most important consideration in
planning, writing, and reviewing a document.
To write effective documentation
that suits the users, we must
understand their needs.
In other words, do not create
a 300-page manual when a
quick reference guide will do.

4. Technical writing is full of complex information.
Do not confuse readers with
heavy information.
Write document to audience's
readability level.
Document should help the readers
to complete their required task.

5. Use active voice to ensure that your readers and users
clearly understand your documentation.
It is commonly held that passive voice is acceptable in
technical writing.
However, overuse of passive voice,
or use of passive voice in long and
complicated sentences, can cause
readers to lose interest
or to become confused.

6. In technical writing, an advance organizer is a bulleted list
at the beginning of a chapter that provides an overview of
the chapter.
The most important single factor
influencing learning is what the
learner already knows.
Advance organizers help users
process and retain information based
on what they already know.

7. Break your documentation into smaller portions using bulleted
lists, shorter paragraphs, and cross-references.
Chunk your documents according
to topics—one topic per chunk.
Chunking keeps the readers' attention,
providing them space to stop
and absorb what they've read.

8. Too much text crammed onto a page intimidates readers
and turns them away.
In technical writing, always use
white space around the text
to break up pages.
Too much text can tire the eyes.

9. Use cross-references to link related information that is
described elsewhere in the document.
Cross references are not essential
to the current discussion.
In online documentation, provide
adequate hyperlinks to cross-reference
related information.

10. Step/action tables provide a practical way to separate
procedural steps from other descriptive information.
This is a very important aspect of
information mapping.
Procedures contained in step/action
tables are easy to read and follow,
increasing document effectiveness.

11. A quick reference summarizes the most common user
procedures, which is very helpful to users.
A quick reference help readers
get started without having to
comprehend a large amount of
information beforehand.