:
Technical Writing Guidelines
Here are some guidelines for technical writing.
Table of Contents
Primary steps 3
The steps in creating a user manual 4
1. Collecting Information 4
2. Generating Content 4
3. Editing and Rewriting 5
See and think from the user's point of view 5
Lay the outline of the manual with a TOC (Table of Contents) 5
Introduce complexity in a graded way 5
The heading tells what the section is about 6
One main idea per paragraph 6
One thought per sentence 6
Language considerations 7
Use numbered lists for giving instructions 7
Use short sentences 7
Avoid verbosity 7
Expand abbreviations 8
Use active voice 8
Make it conversational 8
Write, Edit, and Rewrite 8
Using Images 8
Miscellaneous tips and tricks 8
Checklist for editing and rewriting 10
Primary steps
We call these primary because they affect the structure of the whole document. It affects how the
customer is going to see the manual, and how the information will be presented to him. It is similar to
the foundation of a building.
This clearly demarcates which type of content must go into which section, and what cannot go in there.
This also lays out how the complexity of the information is built up. For example, in the introduction, you
just lay out the bare outline of the function of the software. The descriptions of its different modules and
how to use their functionalities come later.
This does not cover language hygiene aspects like Grammar, Spelling, and Punctuation (GSP). It might
offend some to say that they are cosmetic. They are important; however, the structure is the basis of
user-friendly documentation. Those are secondary considerations, and the second part of this booklet
deals with them.
This booklet definitely does not cover every aspect of technical writing, however, it attempts to suggest
some guidelines for making the process simpler. Hopefully, the end result will be more useful to the client.
The steps in creating a user manual
You can use these steps in creating any technical document–reports, manuals, installation guides...You
may need to tweak them a little as per the type of document.
Collecting Information
You can collect information on software in these three ways:
Researching- Research the web or technical books
Interviewing- Conduct research with SMEs (Subject Matter Experts) and developers.
Using the software yourself.
Generating Content
Use Free-writing to generate content, to dig out the ideas in your subconscious mind.
Free writing or Stream of consciousness writing is the process of recording your thoughts without
judging them in any way. That is, you transfer them to the keyboard or paper without thinking about
their value or correctness.
How to free write:
Set a timer for 1-5 minutes and write non-stop till the time is up.
Do not stop to check grammar, logic, facts, flow, or spelling.
Don't bother to check if what you’re writing is correct.
Switch off the editor critic in your mind for now and just write.
Just write non-stop.
If you don’t get anything to write, just write the heading over and over. The point of the exercise
is to release your inhibitions.
What you generate from freewriting are crude ideas, unpolished work. At a later stage, you can
edit and rewrite it to make it readable.
Editing and Rewriting
Here is where you shape the text that you have generated through free writing into meaningful content
that users can use. Generally speaking, the more you edit and rewrite, the better it gets.
See and think from the user's point of view
The user will be reading the manual only to complete particular tasks.
For example, adding a user, generating an xyz report,...
So our TOC and index has to cover all possible angles from which users may search
This is somewhat like Google search.
As the user is not familiar with our software, they're not likely to know of its various modules, so they'll
search only by the task/function they have to perform.
Lay the outline of the manual with a TOC (Table of Contents)
Now when a user looks at the TOC he/she will see a lot of unfamiliar names–ABX, NDR, XDR,... A
person who has experience in the field will know how to make sense of these. However, it is very
unlikely that every user will be at that level of expertise.
So when you say ABX panel in a heading, try to include some term that shows the function of the item
such as “ABX control panel“, “Viewing the logs of XYZ”, or “ Adding users in the ABC dashboard” etc.
If it's absolutely impossible to show the heading as a task/function, you can just write it as it is. However,
the first section needs to be with the subheading “What is ABX panel” or something like that introduces
the user to the item.
Introduce complexity in a graded way
In the introduction, do not try to make the perfect explanation of the functions of the software. Just try to
give a simple outline of what the software can do. You can give more detailed explanations when
describing each specific task/part later.
The heading tells what the section is about
Make everything in that section about that heading. Fiction writers have some leniency to wander;
however in technical writing, the user is hard-pressed for time, confused, and likely stressed. Just
keep it straight to the point. After your first round of free writing, in the editing round, ruthlessly
move/remove all that is unrelated.
One main idea per paragraph
If the para is on “Adding users”, stick to that topic.
Don’t describe other functions in the same para.
Don’t describe other parts.
Do not explain how that function works.
Stick to instructions on adding users in this para.
For the other topics, have separate paras.
One thought per sentence
Readers can’t keep too many ideas in their minds at the same time.
Language considerations
Use numbered lists for giving instructions
This helps you check the sequence of steps that the user has to perform to complete a task.
Example:
Use short sentences
Use short sentences–most of the time, that is. Mix them up with a few longer sentences, so as not to
feel jerky.
Avoid verbosity
Use simple words that people can understand easily.
Examples:
Expand abbreviations
Expand abbreviations the first time you use them in a document. Don’t assume the reader knows them.
There may be more than one expansion.
Use active voice
Use active voice as much as possible. This gives more power to your writing. That is, the content drives
itself into the reader’s mind.
Make it conversational
Having a relaxed tone, avoiding jargon, and trying to always see from the reader’s level will help give the
feeling of a conversation. However, avoid a chatty style.
The right tone comes naturally out of wanting to help the user.
Write, Edit, and Rewrite
It gets better with rewriting.
Using Images
Images need captions.
They should be clear.
If you are showing a closeup of a part, first show the part in the context of the larger picture.
Otherwise, the user will not know which area you are referring to.
Images need to have borders
Miscellaneous tips and tricks
Upload the .docx file to Google docs or start from scratch on Google docs. Thus many people
can work on the same document at the same time. Version naming and storage is also easier.
When you start formatting the document you can download and work on desktop MS Word.
If you are using Word, insert cross-references at the final stage because these make the
document slow.
Try to make an image as a single unit that has no danger of losing its parts. That is, if you insert
text boxes and arrows on images, they may move about while you work on the document. It is
safer to place them, take a screenshot and then insert it, or better still, use an image editor to
insert arrows and text and then save.
Bolden the names of screens, and screen elements (buttons, fields, etc)
While working with large documents with lots of images, Word becomes slow. It might be better
to split the document into chapters, each a separate file. After the work is complete, you can
merge them all.
Checklist for editing and rewriting
*Structure- (headings, ordering of content etc)
*Content editing and rewriting--
-numbered lists for instructions, bullets for everything else
-passive voice to active voice
-Shorter sentences
-Eliminating/reducing verbosity, jargon
-Abbreviations in the proper way
-GSP check (Grammar, Spelling, Punctuation)
-Capitalization
. .....
-Caption images
