the art of technical writing

– The templates
provided by HPGM-AS are pretty good. If we are using a template – then for
each section really read the section description given in the square
brackets.

– The document
should be written objectively, with no ‘I’ or ‘You’ involved. Everything should
be “impersonal”. We can avoid he/she by directly using the words like
‘user’/’administrator’, etc wherever it makes sense. Also, we can user
phrases like “one want to configure XYZ utility, needs to copy ABC file to ‘x’
location”.

– Informal acronyms
must be avoided, e.g. use “database” instead of “db”, “phone” instead of
“ph”, “number” instead of “no.”. Expand abbreavations used, if any, to avoid
confusion

– First
jot down some rough notes (non-electronically, i.e. with paper and pen!) the
outline or the important points that you plan to put in. Maybe expand some of
these points, to add more details. Use a mindmap if you like the
idea.

– Put
yourself in the place of the reader – say
not just what you want to say but also what a reader of the document wants to
know.

– Nothing to be written just for the sake of writing or just for the sake of filling up a paragraph.

– Write only
relevant matter. Use careful consideration before
attempting to explain underlying technology which a reader is
expected to know. For example in a design document for a particular
component, its unnecessary
to explain a servlet is or
what a relational database system is. It is
unnecessary to include diagrams of the architecture of a weblogic
application server, etc – there must be no generic
technical redundancy.

– Author must honestly ask and answer questions
like does the target audience have everything she needs from this
section/document? What else is required, or what is lacking? Clearly
identify and mark the unknowns.

– A picture speaks a thousand
words! Make liberal use of diagrams. Go with UML notation (using
Microsoft Visio, and not the drawing tools Microsoft Word or Paintbrush) as
much as possible.

– Maintain the continuity of the reader’s experience – do not
break the flow. She shouldn’t suddenly get hit by a diagram, and wonder
‘oh what’s this about?’ Every
diagram should be preceded by
an explanation that maintains the continuity of the previous section.
So each diagram must first have atleast a brief paragraph on the lines of “The following diagram illustrates the
… and each of the components shown are explained in the following section”. It
should explain the purpose of the
diagram, an overview of the components in the diagram and maybe references to
other sections where individual components of the diagram are explained in more
detail.

– Take care of the
past/future/present tense depending on the context. In a requirements
specification, the sentences usually have “The system will have this feature”.
In a design document, it will be written as “The system has this
feature”.

– Please run a spell
and grammar check! (Try
to avoid dependency on these tools, and learn & remember the right spelling
and grammar that it points out. Learn to avoid typos as you type instead of
correcting them later. Document after document, its possible to iteratively
improve such that there are fewer and fewer errors over time!)

– Careful use of vendor names,
whenever any vendor name becomes compulsory to mention. It should be impersonal,
in a positive way, and should not lead to any confusion to vendor, reader,
writer, and as well as the company that writer
belong.

– After finishing a draft version of the document,
completely forget about it a while – do
something else! And then later, review the document from a
fresh perspective, as if you’re reading someone else’s document.
Taking a hard copy and reviewing with a pencil/pen is useful. Check if
the document says what was to be said, whether it is going to the right
audience. Then get the revised document
reviewed
by colleagues as well.

– Keep simple things simple. “Things should be made as simple as possible — but no simpler” ~ Einstein – so its a matter of balance 🙂