Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
By David Odell
(1) Place the Figure Titles Above the Graphic
When you are linking some text to a relevant graphic in a desktop publishing or word processing package everything will seem fine and you go directly to a view of the illustration. The problem begins when you create PDF files that have these links in, whether they are from the contents list or from inside the body of the text. More often than not if you click on the link then you will be taken to the location of the figure title and not the figure. This will appear at the top of the screen and then the reader has to scroll up to see the illustration they were seeking. This is not very user-friendly. The simplest way to solve this problem is to put the title above the illustration and then the title will appear at the top of the screen but at least the illustration will be visible underneath it,
(2) Use Sensible Filenames for Graphics
A lot of companies do not have any standard naming conventions, but a lot of times the file name for the illustration relates to the position it is in the document, such as fig_1_3.png or fig_chap1_13.png. Giving files names like these are of no help to either the author who may take over the document, or an illustrator who has to modify the illustration. One obvious problem is that you might want to add a section to a chapter that also needs an illustration, therefore the file no longer matches the position it is in the document. A further problem is that if you reuse a certain illustration within the same document, do you give it 2 different filenames or the same so that it also bears no reference to its position within the document. A far more sensible naming convention is to use a name that actually describes the illustration so that it can be easily identified within the file system or CMS you use.
(3) Annotate Your Graphics
A lot of times illustrations are annotated within the graphic program in which they were created. This can cause a lot of problems, and extra work, on many levels. If the document is to be translated the translator has to be able to use the graphics program involved, if names of certain objects are changed then the illustrator has to go back to the illustration to change it, the same is true if a spelling error is found on the illustration. If annotations must be made within the graphic program then it is best to use numbers, then a table can be used within the document body text. This will make for easier translations and text changes. Many word processors and desktop publishing programs now allow you to do call outs in the program itself so the author can do annotations over the graphic that has been imported. This is by far the best way to work as it also allows for editing and translation, and also does not mean there have to be mini tables throughout the document.
(4) Importing a Graphic into Your Document
When placing graphics within a document you are usually offered two options. You can either paste the graphic in position, or import it by reference. A lot of people still use the pasting option as they are concerned that the graphic will not stay with the document when it is sent to somebody else, but the recommended method to use is to import by reference. This not only reduces the size of the file, it also means that the graphic can edited and updated without having to access the document, and if the graphic has been used in other locations, all of these images will be updated automatically as well. If you had used the pasting option you would have to hunt through the document and delete and then insert the graphic each time it is used. Follow these simple tips and you will not only make the development of your document easier, and run a lot smoother; but you will also make life easier for your audience who will read your documents on-screen.
Freelance Technical Writer David Odell has been writing technical manuals for companies all over Europe for over 25 years. During this time he has used numerous pieces of software and methodologies. He has two web sites, Technical Authors Resources that gives advice and information on technical writing, and The Write Advice that covers all genres of writing.