---

Published 31 January 2002.
Revised 25 February 2002 (Interleaf => Quicksilver)

---

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 based help is the current winner for on-line help
• Single sourcing 
• Machine (aided) translation
• Monitors and screen resolution
• Possibilities with colour laser printers and photocopiers
• Using camcorders and ScreenCams for technical documentation
• Electronic still and video cameras are gaining use
• Print on demand = "In-line" manual production
• Increased interest in interactive multimedia manuals
• Electronic file transfer to the print shop
• 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 are that it is free, and that it (like HTML) is multi-platform – it has even entered the Windows world. The major drawback is that it – with the software currently available – is not WYSIWYG.

• XML, which is another HTML-like language currently gaining significantly growing interest mainly because it is suitable for the production of single source paper and on-line documentation, and because it is platform independent. Especially the larger companies are increasingly working with XML. The problem is lack of suitable user-friendly editors, but plug-ins exist for MS Word 2002 and Adobe FrameMaker.  Basically the system consists of two document types: 
• A content database-like document with all texts blocks related to a document. A text block could for example be the product data.
• A document specifying which blocks are to be selected and placed where in which format in the final document.
  

• Simple editing, short/medium size documents: MS Word 10/2002/XP. MS Word is basicaly an advanced word processor with some DTP (desk-top publishing) facilities. Word X is fairly stable, almost on level with Word 97 SR1, but it has a large number of more or less useful new facilities, also compared to Word 2000. Lotus WordPro still exists in Lotus SmartSuite, now in version 9.7 (Lotus is now owned by IBM, which will keep it alive for some years). Corel WordPerfect still exists in WordPerfect Office 2002. Both are rarely mentioned or seen in the techwriting sector.
• 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 directly and 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 still in version 6.0. FrameMaker is basically a DTP programme optimised for text handling. Its closest competitor in this sector is the XML-oriented Broadvision Quicksilver (ex 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 and InDesign. PageMaker is now in version 7.0 and seems to survive! The more complex InDesign is now in version 2.0. Corel Ventura (since 2000 in version 8) 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 of its high price and because it's too complicated compared to the needs of most users and because of competition from mainly 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 (but version 5.0 is the current one) 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.) seem 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: 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 (still 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. There are LOTS of competitors, but to my knowledge none are really on par with Paint Shop Pro.

• Screengrabbers: A lot of programmes and no clear winner:
• Techsmith SnagIt 6 (shareware) – still looks more and more like a potential winner.
• Jasc Paint Shop Pro 7 (shareware) – very popular, too. *)
• Adobe Photoshop *)
• Full Shot
• IMSI Hijaack (Pro) *)
• Hypersnap
• Snapshot
• Capture LITE/Pro
• Lview (shareware)
• PrintKey 2000 (freeware)
• PhotoImpact
• 20/20 (freeware)
• Windows users: Of course you can use the Windows PrintScreen = Grab full screen and Alt+PrintScreen = Grab active window to clipboard, paste it into a text/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 seem 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.
 
• Animation Screengrabbers are able to capture "movies" from the PC/Mac screen, typically as AVI files. The available PC software is e.g.
• Techsmith SnagIt 6 (shareware). I have used it recently for a small (2.9 MB for 2 minutes) AVI instruction, which you can download together with the AlarmClock PC-application (freeware from PRC).
• Techsmith Camtasia (shareware). More advanced facilities than SnagIt.
• IMSI Hijaack Pro
• Hypercam
• Lotus ScreenCam
• Microsoft Camcorder (comes with MS Office 97). Works with Windows 95/98/Me, 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 mainly UNIX and LINUX systems are sharing the rest. 
• LINUX (the free Windows competitor) is still gaining ground for large systems and servers, but it is less used for workstations.
• Thin client systems like Microsoft Office on Citrix are still too primitive for many technical writing applications. It is for example not possible to include plug-ins, you still don't have on-line help applications available, and you cannot make PDFs. (Please correct me, if I'm wrong!)
  

---

HTML based help is the current winner for on-line help

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

IFlat 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 quite expensive, but 1600x1200 15" screens are becoming popular for high-end laptops. 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. A new development is the PIVOT function, where you can rotate the screen 90 degrees and consequently display one A4 or Letter Page on a full screen. 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 two projects were both 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 were 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. In November 2001 I bought a DV digital camcorder which improved the quality significantly. Some of the video sequences will be used for 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. With my new digital video systems (DV) it is possible in many cases to to use extracted single frames in a suitable quality to a printed size up to 12 x 15 cm (4.7 x 6").

• The third project was 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. The idea died because of microphone problems (most PC microphones are not sensitive enough.

• The fourth project was on internal documentation of a huge and very complex IT system. Here I used video for recording the "papers" given by the engineering staff about what we were to write about. This was very useful because very often we didn't understand everything the first time. We needed information from e.g. other engineers first, and they were not available in the most suitable order. With the video we could go back and play it again several times until we have understood and extracted all the information given.

• The fifth project was an internal demo project, AlarmClock. The project demonstrates the very significant difference between  – and combination of  – normal on-line help and video tutorial. Here I used SnagIt 6 for capturing the 5 frames/sec video sequences and recorded most of the the sound afterwards. Again there were problems with the sound level and quality. In the AlarmClock tutorial the problems are only partly solved, but I now know what to do better next time. AlarmClock is freeware and can be downloaded from here (3.67 MB).
  

Electronic still and video cameras are gaining use

• 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".

Print on demand = "In-line" manual production

Increased interest in (interactive) multimedia manuals

The advantages are:

• A CD-ROM or DVD is much cheaper than a book/booklet.
• Many languages on one CD-ROM or DVD...
• solves the multi-language problem without disturbing the user.
• gives 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 only got an ink-jet printer, which is 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 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 to 16x+ writing speed and become cheaper (~100+ 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. The media are now fairly cheap (~2 US$ for a 650 MB media), the writing speed has increased to 10x, and the formatting time has been drastically cut. Consequently, they should be able to gain more ground. I use them a lot for internal use, also because all modern CD data readers can now read them.
• The DVD-R (read-once) and DVD-RW (~ diskettes) with 4.7 to 9.4 GB data capacity will be taking over from the CD-ROMs as the general standard. DVD-R readers are cheap, currently down to ~40 US$. The write-once media are still quite expensive (~15 US$ single sided) , but the prices are rapidly falling. The DVD-RW recorders/readers has become cheaper (US$ 1000+) and the media prices are now down to US$ ~15. The common DVD-R and RW standards are still not definitively selected.

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 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.

.

.

.

.

.

.

.