Return to Technical Communication Resources Page | Return to CIT Home Page

Topic 11: Using graphics & On-line doco

Most professional, technical writing contains graphics--drawings, diagrams, photographs, illustrations of all sorts, tables, pie charts, bar charts, line graphs, flow charts, and so on. Graphics should be used wherever the situation demands.

Graphics can be produced by a range of software applications:

CorelDraw & CorelPaint
Excel
PowerPoint
Word

Graphics: an overview

You can use graphics to represent the following elements in your technical writing:

Objects –photographs, drawings, diagrams, and schematics illustrate objects – like how to install a circuit board into a computer.

Numbers – tables, bar charts, pie charts, and line graphs can illustrate numerical data.

Concepts - depicts non-physical, conceptual things and their relationships. For example to illustrate an organisation.

Line drawing

Diagrams

Diagrams are a more abstract, schematic view of things, for example:

Photographs

Line drawings, diagrams and photographs are generally used as follows:

Instructions – use line drawings. They simplify the situation and the objects so that the reader can focus on the essential details.

Descriptions - use drawings with more detail, such as shading and depth perspectives.

Feasibility – in recommendation, and evaluation reports, photographs are often used.

Formatting requirements

Labels – most illustration would contain labels-words and phrases-with pointers to the parts of the things being depicted.

Keys – where the illustration has shadings, colours, line styles, or other such details that have a special meaning in the illustration, these should be indicated in a key--an area in an unused corner of the illustration that deciphers their meaning.

Titles - illustrations should have numbered titles (Figure 1, Figure 2, etc) Except where there are too many to number.

Cross-references - illustrations should be referred to from the relevant point in the discussion. Do more than just "(See Figure 2.)"; discuss the illustration - focus readers' attention on the essential details of the illustration.

Location within the report - place illustrations just after the point where they are needed, or at the top of the next page.

Size of illustrations - illustrations to be between one-half to one-quarter of the vertical size of the page. You want them to fit on the page with other text.

Placement within margins - illustrations to fit between standard margins. Allow two blank lines above and below the illustration.

Level of technical detail - illustrations to be at the right technical level for your readers. No chip circuitry diagrams for computer beginners.

Producing illustrations

Photocopying is easiest. Trim off the figure titles and other unnecessary text.

Scanning.

Clip art

Hand-drawing

Elements of a pictorial graphic.

Notice that you can use a simpler means of indicating the source by using the same format as in regular number-system citations.

Photographs

Scan, then insert into the document

Tables

When to use. Use to represent numerical data to compare and contrast things about which you provide the same categories of detail. For example, comparing several models of a laser printer: you'd be saying the same category of thing about each printer (it's cost, print speed, supply costs, warranty terms, and so on).

Table format. The simplest table is a group of rows and columns of data with a column heading, which defines or identifies the contents of that column When rows or columns must be grouped or subdivided, use subheadings:

Producing tables. Use Excel or something similar.

Charts and graphs

Charts and graphs are another way of presenting the same data that is presented in tables - though more dramatic and interesting.

General guidelines for graphics--a review

Use where possible. Use graphics whenever they would normally be necessary

Appropriate to your audience, subject matter, and purpose - don't hit beginners with advanced, highly technical graphics.

Intersperse graphics and text on the same page.

Figure titles for all graphics.

Indicate the source of any graphic you have borrowed

Identifying detail such as illustration labels, axis labels, keys, and so on.

Fit within normal margins.

Photocopy. When you tape graphics in to your report, photocopy your entire report, not just the pages on which the tape-ins occur. Hand in the entire photocopied document, not the original and not a mixture of original and photocopied pages.

No manual colouring or other detail on the pages of the final copy.

Close to relevant text. Put graphics as close to the relevant text, otherwise, at top of following page.

On-line documentation

Covers producing technical documentation in HTML and PDF, and general design strategies.

An excellent guide to designing and producing HTML from Yale University (recommended):

http://info.med.yale.edu/caim/manual/contents.html

Technical docs in web format

Internet/Intranet. Use either HTML (Hypertext Markup Language) or PDF (Portable Document Format) – requires plug-in, downloadable from www.adobe.com

HTML/PDF Export Filters. Most WordProcessors and DTP Packages now have export filters to both these formats.

Images. Use either GIF and JPEG. Keep them small to minimise download time.

Imagemaps. (also known a graphical information map) is a 2D image that is been "mapped" with links. It has clickable regions that are linked to other pages on the Web.

HTML design strategies

Presenting any information is governed by your objectives, the practical logistics of the medium you choose, and by the nature of your audience.

Four major themes for intranet/intranet information delivery against two fundamental variables: how linear the structure of your presentation will be, and how long the typical user contact time will be:

Web surfers

Most web surfers are unmotivated readers who may blow through your home page without an urgent mission or purpose in mind.

The categories of Web that follow are typical of corporate and educational "intranet" sites where the users arrive with a more defined purpose.

Training

Web-based training applications tend to be linear in design, and present few opportunities to digress from the central flow of the presentation. Don't confuse users or confound your own expectations by offering many links away from the central message. Restricting the links to "Next" and "Previous" paging functions guarantees that everyone sees the same presentation, and allows you to make more accurate predictions of user contact time.

Assume a contact time of less than one hour, or are broken up into sessions of an hour or less. Inform your users about how long the session will last, and warn them not to digress away from the required material if they are to get credit for the training.

Teaching

Good teaching applications are also built around a strong central narrative, but typically offer more opportunities for students to pursue interesting digressions from the main themes of the Web site. The information presented is usually more sophisticated and in-depth than in training applications.

Links are the most powerful aspect of the Web, but they can also be a distraction that may prevent your students getting through the basic presentation. If you want to provide students with links to other Web-based resources beyond your local site you might consider grouping the links on a page separate away from the main body of the material. Often users will want to print the material from the Web and read it later from paper. Make this easy for them by providing a "printing" version that consolidates many separate pages into one long page.

Education

The audiences for heuristic, self-directed learning will chafe at design strategies that are too restrictive and linear. Often the typical user is already highly educated. Flexible, interactive, non-linear design structures are ideal for these users, because it is so difficult to predict exactly what topics will most interest an experienced professional or graduate student. The design must allow fast access to a wide range of topics, and is typically very dense with links to related material within the local Web site and beyond on the World Wide Web. Text-based lists of links work well here for tables of contents and indexes because they load fast and are dense with information, but this audience is also easily bored and needs the frequent stimulation of well-designed graphics and illustrations to stay involved with the material. Contact times are unpredictable, but will often be shorter than for training or education sites because the users are usually under time pressure. Easy printing options are also necessary for this audience.

Reference

The best-designed reference Web sites allow users to quickly pop into the site, find what they want, and then easily print or download what they find. Typically there is no "story" to tell, so the usage patterns are totally non-linear. Content and menu structure must be carefully organised to support fast search and retrieval, easy downloading of files, and convenient printing options. Keep the graphics minimal to speed download times, and you may want to investigate search software instead of relying exclusively on index-like lists of links. Contact time is typically brief, the shorter the better.

Return to Technical Communication Resources Page | Return to CIT Home Page