Tip of the month from
Current trends in technical
Minor updates: 5, 12,
13 & 23 Jan., 17 Feb.and 22 Mar. 2000
Published: 4 January 2000
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
If you have corrections, better texts or suggestions for improvements,
please let me know
Preferred software for technical writers
Over the last years, the winners
of the software race have become clearer. Two software houses have taken
distance from the other ones: Microsoft in the office sector, and Adobe in
the professional graphics world. Their strongholds are Microsoft's almost
monopoly on the operating system for PCs (DOS, Windows), and Adobe's control
over the de facto standard for the professional printers, PostScript, which
is also the basis for Adobe Acrobat. This trend has even become stronger
This trend means conversion
of manuals incl. macros from e.g. WordPerfect to MS Word or PageMaker, and
has been involved in such projects in 1998.
The winners within technical
writing depends on the application:
Simple editing, short documents: MS Word 97/2000. MS Word is basicaly
an advanced word processor with some DTP (desk-top publishing) facilities.
Word 2000 seems to be the exception from the rules that new Microsoft programmes
are extremely bug-ridden. Its stability looks like that of Word 97 SR1 (still
not perfect!), but it has a number of new facilities of which I have found
the new multilevel cut&paste function the most important one. Lotus AmiPro
has become WordPro and part of their SmartSuite, and Corel WordPerfect is
now part of CorelOffice 2000 but both are rarely mentioned or seen.
- Advantages (compared to FrameMaker
- Very easy, uncomplicated
"normal" editing facilities.
- Relatively low price, especially
when included in the MS Office packages.
- Everybody else has got it,
so proofing is easy.
- Placing graphics is easy,
but a bit clumsy compared to previous versions (why is "Place over text"
a fixed first option?)
- Disadvantages (compared
to FrameMaker and PageMaker):
- Problems with long documents.
The limit depends on the RAM available, and linked non-embedded graphics
helps. The "Master Document" function is still deeply unreliable and should
- Automatic page shifts are
not stable because they are printer and "normal.dot" dependent.
- No colour separation
- Some problems with "disappearing"
- Available for Windows and
Long (50..100+ page) text oriented documents: Adobe FrameMaker
, currently in version 5.5.6. FrameMaker is basically a DTP programme optimised
for text handling. It's closest competitor in this sector is Interleaf which
is much more expensive and (consequently?) far less used.
- Advantages (compared to Word
- Very stable.
- No problems with long documents.
- Handles colour separations
for colour printing.
- Available for Windows, UNIX
- Disadvantages (compared
to Word and PageMaker):
- High price.
- A reputation for being a
little difficult to learn and less user friendly than MS Word.
- Compatibility problems to/from
- Proof-readers must have
it, too, if electronic proofing is used, and that's costly for e.g. technical
control of the document.
Graphics intensive documents:
Adobe PageMaker, currently in the new version 6.5 Plus. Adobe
InDesign will probably become the winner on long terms, but many users seems
still to hesitate using it. Corel Ventura has still got very faithful friends,
but seems dying. Quark Xpress for Mac/PC is still the king among the top
professional graphics people, but seems to be loosing ground because its
high price and because it's too complicated compared to the needs of most
users and because of competition from Adobe InDesign. Corel Draw never became
the competitor it was aimed to be. Macromedia FreeHand seems to be gaining
ground here, but still on a low level.
- Advantages (compared to
Word and FrameMaker):
- Easy to learn "true" professional
- Advanced functions available,
e.g. by writing scripts.
- Handles colour separations
for colour printing.
- Easy creation of Adobe Acrobat
- Disadvantages (compared
to Word and FrameMaker):
- Text editing is a bit clumsy.
- Separated modes without
auto-switching between graphics and text.
- Bad import/export facilities
- Available for Windows and
Mac, only. Windows and Mac generated files are not 100% compatible.
Document transfer: Adobe Acrobat (.pdf) has become the de facto
standard format for the transfer of documents for printing & distribution
for proofing, especially where the receiver doesn't have the original application
programme (e.g. PageMaker or FrameMaker). More and more printers now accept
or even prefer to receive documents as .pdf files. The MS Office formats
(.doc, .xls, etc.) seems to be the most commonly format used for the exchange
of business documents. Rich Type Format (.rtf) is useable, too, in many cases,
but (undeserved?!) less frequently used.
Vector drawing programmes: There is no clear winner yet, but Adobe
Illustrator and Visio still seem to have won over Corel Draw, especially
for technical oriented drawings. FreeHand is becoming more frequently mentioned;
it has multipage facilities and is used for DTP work, too. AutoCAD is still
dominating in the engineering drawing world but AutoCAD compatible competitors
are popping up which will probably force the prices down.
Raster (bitmap) drawing/handling programmes: In the simple end,
Paint Shop Pro (now in version 6.01) seems to have won the race and is now
moving into vector graphics, too. In the high end, Adobe PhotoShop is still
the preferred tool, but it doesn't have the monopoly it previously had.
A lot of programmes and no clear winner:
Currently Paint Shop Pro and
SnagIt32 seems to be the most used ones. Personally, I find SnagIt32 more
user friendly for making series of screenshots. Some people use the Print
Screen key, which can grab the whole screen only. The above mentioned programmes
can grab selected protions of a screen, e.g. a window, a bar or a button.
*) These programmes are more general programmes including screengrabbing facilities.
are able to record "movies" from the screen, typically as AVI files. The
available software is e.g.
Computer systems: PCs with Windows have captured some 85 to 90
% of the techwriting market. Mac and to some extend UNIX systems are sharing
the rest. The new impressive Gigaherz Mac is hoped to give Mac a new life.
OS/2 is dead! LINUX (the free Windows competitor) is still gaining ground
especially for large systems and servers, and it's supported by companies
like IBM, Oracle and Corel.
HTML help has gained ground. The
viewer (hh.exe) is included in Windows 98 as standard, and it is used for
Microsoft's own applications.
HTML help has gained ground
For more info about HTML help
in general, see Tip of the Month November 1998
Machine (aided) translation
Machine translation will
not be the final solution to all translation problems in the forthcoming
years, but the systems are still becoming better and better. The status today
is, that the better systems are very useful for making a raw translation
before the human translator takes over and makes an - also linguistically
- correct translation. An example of multi-language machine translation using
Babelfish/Systran software can be seen on the
Internet search engine. Systran can currently only translate between some
combinations of English, German, French, Italian, Spanish and Portuguese.
Translation memory ("TM")
systems for computer-aided translation has become more and more
common in the professional translation sector and here the
Translator's Workbench seems to be on its way to become the de facto standard.
Microsoft owns 20% of Trados and use it internally. Equivalent competing
systems are Translation Manager 2.0 from IBM, Déjà Vu 2 from
Atril and STAR
Computer-aided Translation System.
Trados in short:
Dictionaries on CD-ROM
has become very common. They integrate well with the major word processors,
and they speed-up the look-up process significantly, generally leading to
more use of dictionaries and consequently better and/or faster translations.
For some odd reason (which cannot be the production costs!) they are often
more expensive than the equivalent paper editions. Before buying, please
note that there may be major differences in the quality of the dictionaries
not necessarily reflected in the price. Ask around before you decide to buy.
Running in the background as you translate, Trados Translator's Workbench
compiles a database of source sentences together with their translations.
When new text is sent to the Workbench, it immediately compares the sentences
with the content of the database management system. As soon as the program
identifies identical or similar source text, it is displayed along with the
stored translation. All you have to do is simply confirm, complete or edit
the suggested translation. You will never need to translate the same sentence
twice. Translator's Workbench also offers automatic conversion of dates,
numbers and measurements, bilingual concordance search, as well as
handling of footnotes and index entries. There are facilities for producing
project time and cost estimates. Since you use your own word processor when
working with Translator's Workbench you can continue to use its dictionary,
spellchecking and thesaurus look-up features. Translator's Workbench can
be easily integrated with Microsoft Word 97, Word 95 and Word 6 with support
for Word 2000 coming soon.
and screen resolution
Surprisingly many technical
writers are still working with 640x480 or 800x600 pixels resolution on a
14" or 15" monitor. 17" CRT monitors are so reasonable in price now (~200
US$), and so much better. A 17" monitor running 1024x768 should be the absolute
minimum. If price is less important, a 19" to 21" monitor is the absolute
preference. Flat screens are also becoming more and more common, and you
can now get a 15" (almost equivalent to a 17" CRT) and 1024 x 768 resolution
for about 700 US$. Larger flat screens and higher resolutions are still very
expensive. For e.g. webpage developers, it is also a problem, that reducing
the number of pixels on the screen reduces the image size proportionally
making it difficult to get the impression of what the page will look like
on e.g. a VGA screen. But no doubt:: flat-screen monitors are the future.
Possibilities with colour laser printers and photocopiers
Colour laser printers and colour
photocopiers are now (January '00) available down to the US$ 1200..3000 range.
This means, that also all of you who are making low volume print of manuals
using laser printers or photocopiers should now consider seriously adding
colours to your manuals. Examples of suitable use of colours:
- Full colour company logo.
- Use coloured warning icons
and/or warning texts (front/background colour).
- Colour the headings or heading
underscores e.g. blue or red.
- Colour the arrows on b/w
drawings to make them easier to see.
- Colour the part of a drawing
you specifically want to draw the attention to.
- Colour photos can in some
cases replace much more expensive drawings.
Print on demand = "In-line" manual production
Print on demand is now an economically
in 1997-98 have shown that ...
The advantages of "print on
demand" are ...
- their system, developed in
co-operation with Rank Xerox worked well.
- print on demand in some
cases is only marginally more expensive (10 to 15%) than the ordinary "printed
manuals on stock".
- user dedicated manuals meant
less calls to their hot-line.
The disadvantages are ...
- Language problem solved.
The customer can get the manual in the desired language(s) without getting
maybe five other disturbing languages in the same manual.
- No stock of manuals (which
may become obsolete.)
- May be tailored to the individual
user's application (if known).
- High flexibility.
- You can make dedicated customer-tailored
manuals to the customers' specific application or user level.
- Slightly higher price (see
- Less conceptual freedom
- Not yet offset printing
quality - but good enough for the purpose.
Increased interest in interactive multimedia manuals
The low prices on and widespread
accept of CD-ROMs means that more and more manuals are distributed as CD-ROM.
The advantages are:
The disadvantages are:
- A CD-ROM is cheaper than
- Many languages on one CD-ROM
- don't disturb the user
- significantly decrease the
number of versions needed
- give the user the freedom
to select language according to personal preferences. E.g. in Denmark,
many people prefer to read the original English text instead of the translated
Danish text, because translation always means a potential risk for errors
- Possibilities for interactive
has been involved in such a project in 1998 including ...
- on-screen text and speech
controlled handling of a PC dummy of the product for demo and tutoring purposes.
- language controlled texts
- introduction video facility.
for making computer controlled spoken manuals for use e.g. with illiterate
has been involved in such a project in 1999.
- The user can go as much
or as little into details as (s)he wants.
- Possibilities for showing
an image of each spare part without loosing the overview of a spare part
- Possibilities for on-line
updating of manuals and software via the Internet.
- Possibilities for generating
and sending fax/e-mail with orders for spare parts, accessories and consumables.
The file formats are expected
to be HTML help
or Adobe Acrobat, combined with executable (.exe) files for on-line tutorials.
- The user must have access
to a PC (or Mac ...)
- Many users prefers to read
a printed version, mainly because:
- they use low resolution screens.
- they are easier to browse
in (but more difficult to search in.)
- they then don't have to
switch the computer on to see the manual.
- they want to see the manual
and the programme the manual is written for at the same time.
- Many users have ink-jet
printers only, which are expensive to use (price per page). That means they
feel you put your costs on them.
Electronic cameras are gaining use
The electronic images are now
gaining use in two ways:
- Electronic still image cameras
are becoming more and more used for documentation purposes. The main advantages
- You can check the image immediately
after the exposure.
- You can take a lot of shots
of the same target and then discard the bad shots without having to consider
- The quality is now sufficient
for both publishing and for use as the base for vectorised drawings.
- Because color printing is
becoming cheaper, colour photos are becoming more and more used instead of
drawings in low volume manuals (e.g. specially made machines). In general,
a colour photo is not as good as a drawing, but much better than a b/w photo
and in many cases "good enough".
- Videotaping the technicians'
instruction of you may in some cases be an advantage. I have used it twice
in 1999, where the product was a large one-of-a-kind machine placed far away
from my desk. The advantage was, that I could go back and see/hear the instructions
repeated. The problems was to find the proper sequence on the tape; this
was solved by making a list of where on the tape which instruction was placed.
I use a Hi8 camera (almost normal TV quality), but a digital camera would
have been better. It was possible to extract usable lo-res single images
from the video to be placed in the manual.
Electronic file transfer to the printshop
- Number one is the Internet.
Even the most conservative printshops are now finally getting an e-mail address
and accept files send by e-mail. Please note, that most Internet Service
Providers has a limit for files attached to an e-mail of typically 2 to 10
- Instead of sending it by
e-mail, you can upload the file (e.g. by FTP) to a secret directory on your
website, ask the printshop to download it from there, and delete it there
- The CD-ROM writers has improved
(2x => 4x to 8x write) and become cheaper (~150+ US$) and CD-ROM (CD-R)
writeable media are available for ~1 US$. This has made home-written CD-ROM's
by far the most accepted media for the transfer of large files.This will
also mean a decreased use of IOMega ZIP/JAZ and Syquest drives where the
media are so expensive (~12 to 120 US$) that they must be returned to the
sender (administration and postage costs).
- CD-RW (or REwrite) (re-writeable
CD-ROMs) has not yet really become popular as transfer media, because special
readers are needed, and they are not yet common. But the media are now fairly
cheap (~3-4 US$ for a 650 MB media), the writing speed has increased to 4x,
and the formatting time has been drastically cut. Consequently, they should
be able to gain more ground.
- The DVD-ROMs (read-only)
and DVD-RAMs (write-once) with 2.6 to 5.2 GB data capacity (single/double
sided) will be taking over from the CD-ROMs as the general standard. DVD-ROM
readers are cheap, typically down to ~80 US$. The DVD-RAM recorders/readers
and are still very expensive (~5000+ US$). Also the write-once media are
still quite expensive (~30 US$ single sided/40 US$ double sided). The DVD
standards are still "under development".
Usability testing is developing rapidly
If you want to make user-friendly
manuals, testing the manual and correcting the errors found is not enough.
Neither is it enough to write the manual in a proper way and then publish
it. You must make a usability test of the design of the product, including
the properly written manual.
In the good old days, you
made six tests, corrected the errors, and if the errors were small you were
through. Not so any longer.
The problem is, that the test
results are not reproducible. They point out errors -- yes -- but to find
at least most of the problems, they are not good enough.
You should most likely make
some series of tests still probably with six test persons each, but with
different sets of questions and probably also with different test leaders.
And it is not only the manual, it is the whole concept (mainly the GUI) of
the product + the manual + in some cases the environment which is under test.
The classical usability lab
with its video cameras and one-way mirrors is also being reconsidered. New
concepts are popping-up and being tested. Typical problems discussed are:
is the test situation changing the results, and if yes, is it significantly
changing the consequences of the test? Are the results of the test too dependent
of the judgements of the test leader?
disagree with these ideas - or have other relevant points, experiences, or
ideas +/-, please e-mail me
for new "Tip of the month" subjects are VERY welcome, too!
to last month's tip
Go to a list of old tips
Return to the User Friendly Manuals' homepage
Free update service
if you want to receive an e-mail whenever this website is updated with
major new information, e.g. with a new "tip of the month" or a new interesting
link. The e-mail will briefly describe the content of the update.