Published 21 January 2001.
Minor revision 12 July 2001.

---

We accept Mastercard/Eurocard/Maestro/JBC and Visa!

---

 The Tip was 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 .

---

Contents

• Preferred software for technical writers
• HTML help is still gaining ground
• Machine (aided) translation
• Monitors and screen resolution
• Possibilities with colour laser printers and photocopiers
• Using camcorders and ScreenCams for technical documentation
• Print on demand = "In-line" manual production
• Increased interest in interactive multimedia manuals
• Electronic still and video cameras are gaining use
• Electronic file transfer to the printshop
• Usability testing is developing rapidly

Preferred software for technical writers

There are two new possible future stars in the techwriting field:

• LATEX, which is an HTML-like language, which can be written directly in a text editor, and which is mainly used for scientific writing. When writing for some scientific journals it is even a demand! The main advantages of LATEX is that it is free, and that it (like HTML) is multi-platform – it has even entered the Windows world now. The major drawback is that it – with the software currently available  – is not WYSIWYG.
• XML, which is an HTML-like language currently gaining growing interest mainly because it is suitable for the production of single source paper and on-line documentation.

• Simple editing, short/medium size documents: MS Word 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, but it is still not flawless. 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 WordPro in Lotus SmartSuite, and Corel WordPerfect in WordPerfect Office 2000 but both are rarely mentioned or seen.
• Advantages (compared to FrameMaker and PageMaker):
• 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?)
• Good PDF export facilities with Adobe Acrobat 4.
• Good HTML export facilities with add-on programs like WordToWeb , which can separate the Word document in one HTML file per section and keep the internal links.
• 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 be avoided. The problem is smaller now because of generally more RAM in the PCs. I'm e.g. currently writing a manual in MS Word 97/SR1, which is now 165 pages with a lot of screenshots – no problems; the PC has 512 Mb RAM.
• Automatic page shifts are not stable because they are printer and "normal.dot" dependent.
• No colour separation facilities (to CMYK). This can however be overcome by exporting to Adobe Acrobat 4 PDF format, which many printshops now accept as input.
• Some problems with "disappearing" images. I guess, that it may be at least partly solved by making the following setting:
1. Open the menu File > Print.
2. Click Settings...
3. In "Printout settings", checkmark "Update fields".
• Available for Windows and Mac, only.
• The internal HTML handling is close to useless!

• Long (100-200+ page) text oriented documents: Adobe FrameMaker , currently in version 6.0. FrameMaker is basically a DTP programme optimised for text handling. Its closest competitor in this sector is Interleaf which is much more expensive and (consequently?) far less used.
• Advantages (compared to Word and PageMaker/InDesign):
• Very stable.
• No problems with long documents.
• Handles colour separations for colour printing.
• Available for Windows, UNIX and Mac.
• 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 MS Word.
• Proof-readers must have it, too, if electronic proofing is used, and that's costly for e.g. technical control of the document.
• More difficult to keep updated if the updating is to be made by e.g. the engineers or programmers because they typically have MS Word but not FrameMaker.

• Graphics intensive documents:
• Adobe PageMaker an InDesign. PageMaker is still in version 6.5 Plus. Adobe InDesign (now in version 1.5) gains ground and 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 DTP programme.
• Advanced functions available, e.g. by writing scripts.
• Handles colour separations for colour printing.
• Easy creation of Adobe Acrobat (PDF) files..
• 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 in general.
• Available for Windows and Mac, only. Windows and Mac generated files are not 100% compatible.

• Document transfer: Adobe Acrobat 4.0 (.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 – the main problems seems to be related to the many (Microsoft controlled) versions.

• 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. Visio is mainly directed towards real technical writing while Illustrator is more general purpose. FreeHand is becoming more frequently mentioned; it has multi-page facilities and is used for DTP work, too. AutoCAD is still dominating in the engineering design world, but AutoCAD compatible competitors are gaining more and more ground and will probably force the prices down.

• Raster (bitmap) drawing/handling programmes: In the simple end, Paint Shop Pro (now in version 7 – version 6 looked like too many problems) seems to have won the race and is now moving into vector graphics, too. In the professional high end, Adobe PhotoShop is still the preferred tool, but it doesn't have the monopoly it previously had.

• Screengrabbers: A lot of programmes and no clear winner:
• SnagIt 5 (shareware) – looks more and more like a potential winner.
• Paint Shop Pro (shareware) *)
• Adobe Photoshop *)
• Full Shot
• Hijaack (Pro) (IMSI) *)
• Hypersnap
• Snapshot
• Capture LITE/Pro
• Lview (shareware)
• PrintKey 2000 (freeware)
• PhotoImpact
• 20/20 (freeware)
• (Of course you can also use the Windows PrintScreen = Grab full screen and Alt+PrintScreen = Grab active window to clipboard, paste it into a graphics programme and handle/save it from there, but to my experience this covers only some of the typical needs.)

Currently Paint Shop Pro and SnagIt seems to be the most used ones. Personally, I find SnagIt more user friendly for making series of screenshots, which is often the need when documenting software. The above mentioned programmes can grab a selected portion of a screen, e.g. a window, a bar or a button, depending of how it is programmed.
*) These programmes are programmes with another main focus but including screengrabbing facilities.
 
• Animation Screengrabbers are able to record "movies" from the screen, typically as AVI files. The available software is e.g.
• SnagIt 5 (shareware)
• Camtasia (shareware)
• Hijaack Pro (IMSI)
• Hypercam
• Lotus ScreenCam
• Microsoft Camcorder (comes with MS Office 97). Works with Windows 95/98, only.
• Software Video Camera (comes with Robohelp )

• 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. LINUX (the free Windows competitor) is still gaining ground especially for large systems and servers.

---

HTML help is still gaining ground

For more info about HTML help in general, see Tip of the Month November 1998 .
 

Single sourcing

Instead they try other combinations like writing the document in MS Word or Adobe FrameMaker and then converting it to HTML. The problems here are mainly:

• Arrows from text into illustrations will not be handled correctly. This can be handled by including the arrow in the illustration.
• Splitting up the document in single pages per chapter. The best programme to do that is to our experience WordToWeb from Solutionsoft .

Machine (aided) translation

Monitors and screen resolution

If price is less important, a 19" to 21" monitor is the absolute preference and the good ones easily runs 1280x1024 or even 1600x1200 with a usable quality – especially if you use "large fonts".

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$, but the development in price/performance seems to have slowed down. 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 photos can in many cases replace much more expensive drawings. Greyscale photos are most often NOT good enough to show the details.
• Full colour company logo.
• Use coloured warning icons and 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.

Using camcorders and ScreenCams for technical documentation

• The first project was the documentation of a tooling system for the metalworking industries. Here a Hi-8 camcorder was used for recording the actual procedures in the workshop. After some methodology development it turned out to be a very cost efficient way to work. The video tape sequences was directly used for writing down the step-by-step procedures making sure all details were covered correctly. Single frames from the video were used for small colour illustrations (typical printed size 4.5 x 5.5 cm ~ 1.8 x 2.2"), either directly or as the basis for semi-automated production of drawings. Larger raster illustrations were made by means of a high-resolution digital camera. The main advantage of using the video camera images was that we could select exactly the right split second of the procedure for the illustration. Some of the video sequences will (spring 2001) be converted to short .avi movie files, edited and finally converted to e.g. .mpg files to be inserted in an PowerPoint presentation to be used for instruction of the workers.

• The second project (started December 2000) is the documentation of a very large and complicated Windows application. After experiments with videotaping instructions from an expert, we are now working on using a ScreenCam application programme + a microphone to record the explanations from the experts. We know the result will be some very large .avi files, but we also expect some significant savings, mainly in the time of the experts.

Print on demand = "In-line" manual production

Increased interest in interactive multimedia manuals

The advantages are:

• A CD-ROM is much cheaper than a book/booklet.
• 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. this is a great help in multicultural companies. Furthermore (e.g. in Denmark), many people prefer to read the original English text instead of the translated text, because translation always means a potential risk for errors or inaccuracies.
• Possibilities for interactive tutorials.
• Possibilities for making computer controlled spoken manuals for use e.g. with illiterate workers. PRC 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 list.
• 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 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.

The file formats are expected to be HTML help , combined with executable (.exe) files for on-line tutorials. Adobe Acrobat will probably become much more interesting if it permits linking to internal anchors – which it don't do today.

Electronic still and video cameras are gaining use

• Electronic still image cameras are becoming more and more used for documentation purposes. The main advantages are
• 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 costs.
• The quality is now sufficient for both publishing and for use as the base for vectorised drawings.
• Because colour 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 technician's instruction of the technical writer(s) may in some cases be an advantage. I have used it for two projects in 1999 and 2000, where in both cases 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 problem 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 video camera would have been better. It was possible to extract sufficient quality (704x576 16M colours) single images from the video to be placed in the manual as 5.5 x 4.5 cm (~1.8 x 2.2") images.

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 MB.
• 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 when downloaded.
• The CD-ROM writers has improved (2x => 4x to 12x write) and become cheaper (~150+ US$) and CD-ROM (CD-R) writeable media are available for ~0.50 US$ or less (mind the quality!). 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 (~2 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 disagree with these ideas - or have other relevant points, experiences, or ideas +/-, please e-mail me !

Ideas for new "Tip from PRC" 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 .

Free update service
Click here 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.

.

.

.

.

.

.

.