Tip of the month from PRC
December 1997
The modest demands to a good
techwriter
Released 7 December
1997
Linguistic improvements 8 December 1997
We accept Mastercard/Eurocard/Maestro/JBC and Visa!
Tip of the month is edited by Peter
Ring, PRC (Peter Ring Consultants, Denmark)
- consultants on how to write
user friendly manuals
Critical skills :
- Pedagogic sense and knowledge
- An OPEN MINDED understanding
of the users' situation, even if it is very different from your own. A teaching
and/or market research background helps.
Don't forget: as a technical writer, you are in the teaching business. The
purpose of your work is to teach the poor buyers how to use the product you
are describing. And like with all other kinds of teaching, there are some
teaching techniques
which are known to work, and traps to avoid. If you do it right, your pupls
will love it. If you do it wrong, they will discard your manual. And unlike
in school, in this case the pupils can leave the class freely. And they do
if the manual is bad. The loosers in case of bad manuals: first the users
because they can't use the product optimally, then the manufacturer and his
sales organisation because unsatisfied users don't come back.
- Good at precise COMMUNICATION,
also on the weakest users' level
- Writes an easy to understand
and very precise language, - unless it's all text free manuals.
- The ability to reformulate
information. Very often most of the information is there, written by the
designing engineers or programmers. But the organisation of the document,
and the way it's written, makes it more or less impossible to understand
for the users. And frequently important information is missing, often the
mission of the product.
- Able to think clearly
and critically
- Very often the basic information
presented to the technical writer is wrong or contradicting. Here it is the
obligation of the technical writer to find the truth, and describe the truth
- or persuade the designing engineers or programmers to improve the product.
-
Technical insight and flair
- Technical insight and flair
is often critical in order to be accepted by the designing engineers or programmers.
You also need it to find out of the product. If documenting software, some
programming knowledge is a good thing to have. Example: you suggest a GUI
improvement, the programmer tells you it's impossible. But if you know programming
yourself, and therefore know it's possible, you can argue a lot better for
your idea. And next time he will respect you and don't use an easy-lazy excuse
for not doing what he should have done.
- Organisational power
- Prof. knowledge =>
Theoretical frame
for use in meetings, etc. It is useful if you can put words on your ideas
bout who you are writing for, why this readability level, number of illustrations,
etc.
- Good at interviewing, reading
"between the lines", digging up information, asking questions - even questions
others may view as dumb" questions.
- Can influence the technocrats
to make a suitable user interface, if it don't work properly. See
Technical insight and flair
, above.
- Persistent, high integrity,
self disciplined, hard working
- Well, if you have survived
for some time in this profession, you know it !
Critical skills for some kinds
of technical writing :
- Graphical knowledge
(+ sense and flair)
A critical skill unless it is "text only" manuals and your only job is to
write the text.
The technical writer is in
many cases involved in decisions about
- number of illustrations
- the content of the illustrations
- size and cropping
- type of illustrations
- layout
- selection of text fonts and
sizes
- margins
- where to place text, and
illustrations so that linked text, illustrations and tables are viewable
at the same time
- indents and bullets
- selection of icons
- sometimes even printing
technology.
It is often argued, that this
can be left to the graphical people. I don't agree! The graphical people
are trained to make it graphically nice. If an illustration disturbs the
"optical balance" on a page, it's moved to the next page, making it less
user friendly. You as a technical writer are responsible for the functionality
of the manual - therefore YOU have got to control the final layout.
Where the graphical people
come in is to make the company graphical style guide for the manuals. In
most smaller companies, where there is no style guide for their manuals,
a graphical know-how can make the difference between an awful graphical mess
and something acceptable or even nice.
- Good at making technical
illustrations
Critical if you are documenting machines, electronic equipment, etc. where
the documentation needs technical illustrations, e.g. front panel drawings.
Not critical if you have somebody else to make the illustrations. But in
many cases it is faster if you can make at least simple technical illustrations
yourself, because then you get them as you want them the first time.
- Good at making non
-technical illustrations
Critical if your are making cartoon style manuals with persons, where the
illustrations are the (main) information carrier.
Useful - but not critical
- skills :
- 100% correct spelling
and grammar - with or without software assistance.
It's the time used and the final result that count, not the tools used. The
reason for putting this point on the non-critical list is that a few
spelling errors, a missing comma, or a few grammatical errors are in fact
not important at the time of writing. The reason is, that the document
will anyway need to be proofed by somebody else, and that it's this
person who has got to be the spelling and grammar expert !
But if you are lacking just *ONE* of the critical skills for your kind of
technical writing - forget it, find something else to do, and don't pollute
the world with more bad manuals!
If you disagree
with these ideas - or have other relevant points, experiences, or ideas +/-,
please e-mail me
!
Ideas for new "Tip of the
month" subjects are very welcome, too!
Go to
last month's tip
.
Go to a list of old tips
.
Return to the User Friendly Manuals' homepage
.
.
.
.