Creating a Style Guide

Article by Colin Battson FISTC

Overview

To help you navigate through this chapter, read this overview first. If you are familiar with Style Guides and merely want to refresh your memory on a particular aspect, it may save you time. The chapter comprises a series of numbered sections, as follows:

Section 1

The first section defines the term ‘Style Guide’. Do not confuse with ‘writing style’. A Style Guide defines features such as page size, page layout, fonts, numbering schemes, and so on, whereas writing style is all about the way the paragraphs, sentences, and the words within the sentences are structured. Refer to Chapter 5 for further information on Writing Styles.

Section 2

We move on to giving some of the reasons why a Style Guide is needed, and how a well-defined one is of help to all concerned with the documents to which it applies. Not just to the author but all involved with the document production (such as word processor operators, proofreaders, graphic designers, typesetters or desktop publishers and finally printers).

A good Style Guide is also of considerable benefit to the reader or end-user of the document. Clear and recognisable styles in heading weights, fonts, contents lists, numbering systems and so on make it much easier to use a publication. A well-designed Style Guide can make the difference between the document being read and being rejected as unreadable.

Section 3

There are very few documents published that are not controlled by some form of Style Guide, even though there may not necessarily be an associated document actually called Style Guide.

Just think of company brochures for example. They are produced to have a strong corporate identity to promote the company. Features such as the colour, size and position of the company logo and the font used for the company name are all-important. Advertising relies for its success on clearly recognised corporate style. This section examines some of the elements covered by a Style Guide, and some pitfalls to avoid.

Section 4

This section discusses document structures such as chapterisation, use of annexes or appendices and so on.

Section 5

Illustrations and other graphics. Why and when to use them; which types are most suitable for different applications.

Section 6

Style Guide aspects and techniques particular to online documentation.

Section 7

This final section gives some ideas for the important aspects of distribution and issue control of your Style Guide. It is useless to produce a fine, detailed and comprehensive Style Guide if it is not circulated to all who should be aware of it; similarly if it is updated without informing all copyholders of the changes.

Now read on!

Section 1 - What is a Style Guide?

General

A Style Guide could be described as the group of rules that define your information or document design. Although documents produced for diverse purposes are likely to require differences between individual styles, many of the essential elements will be there; only the detail will vary. As examples you may specify your User Guides to be at A5 format, Wiro bound and in colour, whereas the Workshop Manuals produced in accordance with your Style Guide are A4 format, assembled in 4-ring binders, and in black and white.

Creating a new Style Guide – the essentials

If you are intending to create a new Style Guide, first consider the range of document types to be covered by it. The greater the range of document types, the more comprehensive and exhaustive your Style Guide needs to become. It is not uncommon for company Style Guides to be published in (say) a 4-ring binder between one and two inches thick. Planning is crucial. It is important to establish at a very early stage the full scope of the Style Guide, so that design elements and structure allow for all document types to be produced.

Make a list of all the elements that will need defining for the information designer who will use your Style Guide. The following may be considered as merely a typical list for hard copy documents, presented in a hierarchical manner, with the key features sub-divided into further detail. Dependent on specific requirements, your list may differ considerably and may be shorter or longer.

Page Size

1. Aspect (portrait or landscape)

Page Layout

1. Margins 2. Headers and footers 3. Columns (single or multi-column format) 4. White space

Chapterisation

1. Numbering 2. Appendices and annexes 3. Contents lists 4. Glossaries and indexes

Fonts

1. Types 2. Sizes 3. Warnings and cautions

Illustrations and graphics
Vocabulary and spelling standards (for example, UK or US English)
Abbreviations - rules of usage
Issue control

1. Amendment instructions 2. Amendment record

Software and version (word processing, DTP, graphics, etc.)
Storage media, archiving, etc.

Where a Style Guide caters for a range of document types, it could be structured to include a general or global section, followed by separate sections for each type of publication.

For example, if it provides style rules for technical manuals, User Guides, publicity or product brochures, in-house reports, contracts and tenders, Quick Reference Leaflets, and so on, it is clear that there will be conflicting requirements in terms of page size, use of colour, paper stock, etc.

Section 2 - Why have a Style Guide?

General

A well-defined Style Guide is of help to all concerned with the documents to which it applies. Not just the author or information designer, but all involved with the document production. This may encompass word processor operators, proofreaders, graphic designers, typesetters or desktop publishers and even printers.

A good Style Guide is also of considerable benefit to the reader or end-user of the document. Clear and recognisable styles in heading weights, fonts, contents lists, numbering systems and so on make it much easier to use a publication. In some cases the existence of a clear structure can make the difference between the document being read and not being read at all.

Benefits to the author:

If an author follows the applicable Style Guide rules when creating a document or publication, all the basic document design parameters are predefined, saving precious time spent in ‘playing’ with different layouts at the outset.

If the author rigorously adheres to the rules, and is producing just part of a larger document or publication, the parts can be joined together ‘seamlessly’ to produce the whole.

Note: Using the style gallery available in the word processing software will ensure full compatibility of texts produced by different authors, provided that:

(i) The authors all follow the styles defined in the Style Guide, and

(ii) The styles have been set accordingly in the word processors used by all contributing authors.

By following the prescribed Style Guide, an author can be confident that the style of the document produced will comply with house rules or corporate identity requirements of the issuing authority.

Typical house rules

Publication style:

Sizes permitted/recommended (for example, A4, A5, custom)
Paper and covers specification
Binding method (for example, ring binder, comb bound, Wiro bound, perfect bound, etc.)
Page layout standards
Numbering protocols (document, section, page, paragraph, figure, table, etc.)
WARNING and CAUTION standards (fonts, capitalization, symbols, borders, positioning, etc.)
Standard preliminary pages
Contents lists, glossaries and indexes
Amendment policy
Appendices

Publication structure and content:

Definition of publication type (for example, Workshop Manual, User’s Guide, System Manual, etc.)
Standardization of chapter titles per publication type
Definition of content of each chapter type
Chapter dividers (material, colours, tabs – titles or alphanumeric)
Positions of figures (in-text and/or at chapter end)
Examples of page layouts and illustrations
Samples of information (for example, technical data, fault-finding guide, parts list, etc.)

The principal benefits of producing all publications to a well-defined Style Guide are:

Easier planning and costing of new publications
All contributors work to defined and consistent standards; keeps costs down
Input from multiple authors/illustrators without major editing
Publications have a uniform appearance and ‘feel’
End-users can navigate more easily when structure and numbering is consistent
Material from one publication can be readily cut and pasted into another
Printers can identify layout errors before expensive printing has been done
Control of amendments and revisions is built-in from the outset.

Section 3 - Some Style Guide elements

Page layouts

Before settling on a preferred page layout for a particular document type, consider the purpose of the document, the typical end-user of it, the type of information to be presented, and whether the published documents are to be single- or double-sided. If the latter, page layouts must be designed for odd and even (or right and left hand) pages. New chapters or sections normally start on a right hand (odd numbered) page.

Margins and white space

Every page has areas of white space; all documents should be designed with areas of white space to make them visually appealing. Margins are one aspect of white space. Another is inter-line spacing, known as leading (pronounced ledding – a printing term originating from the days when strips of type metal were inserted between lines of text in typesetting.). This is covered in more detail later in this section.

All pages have four margins, (see Figure 6-1):

Top – also called head
Inner – also called Left side or binding margin in single-sided publications or gutter in double-sided publications
Outer – the side margin away from the binding edge (always Right in single-sided documents)
Bottom

Top Margin		Top Margin
Even Page (Left)		Odd Page (Right)
O	I	I	O
Bottom Margin		Bottom Margin
Double-Sided Publication Pages
Top Margin
Right-Hand Page
L		R
Bottom Margin
Single-Sided Page

Figure 6-1 Margins for double and single-sided pages

The Inner or Binding margin (always the Left margin for single-sided pages) must be of sufficient width so that printed material, text and/or graphics, is not lost, obscured or damaged in the binding process.

The Outer margin (Right margin for single-sided) need not be so wide, unless it is assigned for a particular purpose such as making notes or inserting marginal notes or graphics in the document itself.

Top and Bottom margins may contain headers and footers respectively (see later in this section).

Text justification

If all complete lines of type on the page are exactly the same length, and extend to both left and right margins, the text has been justified – implemented by adjusting proportional spacing between words. This gives the document a clean right-hand edge which does look neater, and is particularly useful in multiple column page layouts – see later. This paragraph is an example of justified text.

However, tests have established that fully-justified text is somewhat less easy to read, so improved appearance has to be weighed against readability. Fully-justified text is often used in multi-column layouts, where the right-hand edge of the text helps emphasise the column line.

If text is not right-justified, the style is referred to as ‘ragged right edge’. This style does lend itself to easier revision, and – in a survey carried out in the USA – was favoured by the majority.

Leading (inter-line spacing)

Text is easier to read when line spacing is 1.5 times the character height. Spacing between paragraphs is increased sufficiently above that, to be observed as such without conscious effort. This additional space between paragraphs is also an aid to faster and easier reading, as it gives the reader a natural ‘pause for breath’ point.

The above paragraph is repeated below with reduced line spacing, but using the same font and font size, to demonstrate the reduced ease of reading caused as a consequence.

Headings

Headings are used to label sections of text in a document, and by careful selection of a range of heading styles or ‘weights’, the autor can use readily recognisably different heading styles to identify the relative importance of the subsequent text, thereby creating a structure to the document. The relative importance of individual styles should be designed to be self-evident by judicious choice of fonts and other text attributes.

Headings also serve to break the document into manageable chunks for the reader, again contributing towards making the document easier to read. There is nothing more daunting than turning a page to be confronted with a double-page ‘spread’ of solid text without the welcome interruption of a heading or two and paragraph spaces as natural breaks or pause points.

In a typical word processing software package, the properties of the various heading ‘weights’ (degrees of importance) are stored and indexed by the heading name, which can simply be listed as Heading 1, Heading 2, and so on. If this style gallery, as it is known, is promulgated along with the hard copy Style Guide to everyone involved in document preparation & production, headings will be of consistent style.

Following is just one typical example of heading weights for a range of five heading styles:

HEADING 1 – CENTRED, UPPERCASE AND BOLD TYPE

HEADING 2 - FLUSH LEFT, UPPER CASE AND BOLD TYPE

Heading 3 - Flush Left, Initial Caps. And Bold Type

Heading 4 - Flush Left, Initial Caps. And Normal Type, Underlined

Heading 5: Flush Left, Initial Caps., Normal Type Underlined; In Line With Paragraph Text: Xxxxxx xxx xxxxxxx xxxxx xx xxxxx xx xxxxxxxx.

Page grids

Each page can be envisaged as a grid structure, in which columns and rows are used to define and organise the text and graphics, including headings, headers and footers that make up the complete page. Different grids are appropriate for document types targeted at different audiences. For example, a single-column text grid may be used for technical reports or technical manuals, whereas a two-column variant may lend itself to an Operator’s Handbook or Product User’s Guide.

A three- or even four-column grid may be best for a corporate newsletter. The ‘broadsheet’ newspapers use as many as eight columns in their page grid.

This section of text has been produced in a three-column layout, illustrating the quite different appearance this part of the document has, compared to the single-column layout of the rest of this section.

The text in the first column is unjustified (ragged right edge), whereas the second and the third columns contain right-justified text.

Multi-column layout has the obvious disadvantage that line lengths are shorter, hence readability is reduced unless font size is also reduced considerably. That can also cause readability problems in itself, so is not to be recommended unless absolutely unavoidable.

Observe from the example of three-column layout on the previous page that justified text defines the columns better, but can give a somewhat awkward appearance when inter-word spacing becomes expanded as a consequence. All these factors must be taken into account when designing page layout standards for your Style Guide.

Numbering schemes

Almost all publications require one or more numbering schemes, in order to aid reader navigation and to simplify cross-references. It is important that the Style Guide makes allowance for the full range of numbering systems that are likely to be needed for the documents produced to its standards.

Small, single chapter documents (e.g. a Quick Reference User’s Guide or similar) may require little or no numbering system; even page numbers may be superfluous in some instances.

More complex publications are likely to need multiple numbering systems. As an example, a comprehensive Maintenance or Workshop Manual may comprise more than one volume, and may need a numbering system that controls numbering for:

The publication itself (product code and/or library reference)
Modification record (issue numbers, amendment numbers)
Volumes
Chapters
Sections (sub-chapters)
Pages (preliminary pages often given lower-case Roman numbers; other pages may include chapter number or appendix or amendment number)
Paragraphs (numbered where individual paragraphs contain procedures etc. to be cross-referenced, or as required by a controlling specification or standard, such as MoD publications)
Sub-paragraphs (rules to cover sub-sub-paragraphs also, if applicable)
Figures (possibly different numbering for in-text and ‘chapter end’ figures)
Tables
Appendices and/or annexes

As a general rule, shorter user documents seem ‘friendlier’ if numbering – which can appear to be unnecessary ‘clutter’ – is kept to a minimum. Conversely, larger, more deeply technical publications require fully-structured numbering schemes to reduce the time spent locating wanted detail.

For publications containing numerous chapters, numbering that includes the chapter number simplifies cross-referencing and can avoid confusion. For example, ‘See the System Block Diagram Figure 1-3’ tells the reader that the referenced figure is the third one in Chapter 1.

Terminology and spelling control

It is important that terminology is consistently applied throughout a range of publications. Other standards may also apply, such as AECMA Simplified English. Inconsistent use of terms or the multiple use of different terms for the same thing will confuse readers and should be avoided by defining common terms in a Glossary included in the Style Guide.

Similarly, spelling standards should be defined – for English language documents the basic choice is between UK English and American English. Whichever is chosen, set your Spell-Checker function to the appropriate one in all your word processors, then ensure that the Spell-Checker is always used. All these measures can be covered in the clauses of the Style Guide.

Parts of speech and abbreviations

A good Style Guide will cover these aspects, which are impinging on the areas covered in defining ‘writing style’. Remember that the introduction to this chapter referred to the essential difference between a Style Guide and writing style.

However, in order to minimise diversity of writing styles within the same publication or a family of publications, the Style Guide should include some basic rules, such as:

Use only the active voice in procedures (‘tighten the screw’ rather than ‘the screw should be tightened’).
Avoid the use of the passive voice in description and operation texts.
Always use a term in full the first time you use it, followed by the abbreviation in parentheses. Subsequently, the abbreviation may be used instead of the full term.
Ensure that abbreviations used comply with the relevant standards. Define those standards in the Style Guide.

Structuring the text

Avoiding long paragraphs and long sentences allows the reader to absorb the information with necessary and natural ‘pauses for breath’. Similarly, keeping sentences and paragraphs to cover single ideas and topics also helps the reader to understand the written matter without the need to go back and read the same text again.

The Style Guide should give guidance on these ‘writing style’ aspects to increase uniformity of publications.

Illustrations and figures

Structure the Style Guide for illustrations and figures to include rules so that:

Captions on originals are readable at the finished size used in the publication
All graphics are in portrait format wherever possible (no need to rotate the document 90° to read the information therein)
Boundaries are defined for applicable page sizes (including ‘foldouts’ if appropriate)
Illustrations and figures are positioned as close to the related text as possible. This may not always be possible, for example, where a controlling specification requires ‘foldouts’ to be arranged in sequence at the end of chapters
Illustration/figure titles are positioned in a standard way with respect to the graphic content
Text is not created as part of the graphic if translation is a likely requirement for the publication. If text is necessary, for example to identify components depicted, use text boxes to contain the text to simplify the translation process
Line thicknesses and types are defined to have common meanings, for example extra thick lines for system boundaries, dashed lines for external or optional items, etc.
Exploded views for illustrated Parts Lists are not too cluttered. The usual method is to define the maximum number of items depicted on a given page area
Items numbered on a figure are numbered sequentially beginning at (say) the top left corner and proceeding in a clockwise direction. This helps enormously in locating specific item numbers
For different views of the item included in the same Figure, the projection to be used is specified (first or third angle)
For flow diagrams, the convention of top to bottom and left to right is maintained
For complex diagrams (for example, circuits), multiple sheets of the figure are linked with appropriate continuation marks or symbols to aid understanding
Electronic format of figures is readily importable into the text document, is to a defined version of the software, and is in all needed respects compatible with in-house systems in use. See Specification of Software Tools later in this section.

Tables

To ensure consistency of style, include rules for tables, covering aspects such as:

Position on the page (centred between side margins usually looks best)
Line thickness (perhaps a thicker line for the outside frame and/or between repeated sets of columns)
Use of shading (perhaps heading line only, or every so many lines to aid navigation)
Repeat of headings if a table runs to more than one page
Centring of headings and table data in cells, as appropriate
Font and size of text.
Position and style of table title.

The following simple table demonstrates some of the above points. Notice that, in this example, the font used is the same as that used for this chapter’s body text. The headings and title have been made bold for added emphasis.

Height (cm)	Weight (gm)	Height (cm)	Weight (gm)	Height (cm)	Weight (gm)
1.0	50.25	2.5	112.24	4.0	183.64
1.5	68.33	3.0	131.99	4.5	207.03
2.0	94.81	3.5	157.97	5.0	220.93

Height/weight relationship of samples

Headers and footers

Used to help navigation within a publication, define page headers and footers within the Style Guide to ensure consistency of use and uniformity. Information provided is outside the normal page text area. As the names imply, headers are contained in the top page margin, footers in the bottom page margin.

Word processing software allows you to create almost any style you want. Text can be centred, left or right justified (or all three), and can differ for left and right pages, and for different chapters and sections.

Word processing software allows the ‘automatic’ page numbering to be positioned in the header or footer (more commonly the footer is the preferred location). Page numbers are often positioned centre bottom for single-sided publications, and bottom outside for double-sided documents. Thus the page number for an even-numbered or left-hand page would be to the left side, and for an odd-numbered or right-hand page it would be set to the right side. That convention makes the pages numbers easier to view when turning the pages.

Graphics can also be included, for example a company logo. Whatever style you decide on, remember they are intended as an aid to reader navigation; avoid over-complicated schemes that may confuse the reader. The following simplified example shows a typical arrangement:

Publication Title

Chapter Title

Page

Body

Issue, Date

Chapter/Page No

Specification of software tools

In order to ensure complete uniformity and interchangeability, your Style Guide should include reference to specification of software used in the creation and production of your publications.

Documents produced in hard copy may include soft copy as a deliverable to the customer or end-user. It is therefore necessary that the specific software packages (and versions) used to produce the publications are determined before work begins. For this reason, the Style Guide should at least flag up this requirement, which may be ignored if irrelevant for specific applications.

If your publications include examples that are delivered primarily in electronic format, but must include options to print in hard copy, take care that your Style Guide makes allowance for the tools to be used for this specialised but increasingly frequent requirement. It is a fast moving environment which could very easily make your Style Guide out of date if your specification of this aspect is too restrictive.

Specification of fonts

Today’s word processing and desktop publishing software packages can offer a bewildering array of fonts, a temptation for the author wanting to make a mark by using an unusual one, or a selection from the huge choice on offer. However, please bear in mind possible problems:

If a document created using an uncommon font is downloaded and printed on a different system, which does not have that font, the result may be either garbage or a different (default) font which may introduce unexpected characters.
Mixing too many fonts in the same publication can be irritating and confusing to the reader.
Certain fonts may be difficult or tiring to read.

When specifying ‘standard’ fonts in a Style Guide, remember that most Windows-based word processors will have Times New Roman and Arial fonts. Specification of either will obviate the problem described in the first bullet point above.

The body text of this chapter has been created using Palatino 10 point. Palatino is a font featuring serifs on the font characters, and is considered to be easier to read than a similar-sized sans serif font such as Arial.

This paragraph has been created using Arial 10 point. The difference between the two fonts is quite marked. As mentioned earlier, Arial is widely used.

Except for publicity brochures and similar documents, where font choice may be influenced by ‘artistic’ or corporate identity reasons, the general rule is to severely limit the number of different fonts used in the same publication. However, you may, for added emphasis, want to use a different font for, say, WARNINGS and CAUTIONS.

Earlier in this chapter, you will have seen an example of a hierarchical headings structure. This was created using different subsets of the same font, and is easy to understand, to recognise and to follow. If such a structure were to be created instead using a selection of different fonts, it would be much more difficult to remember and could make navigation within the publication less easy.

Font size is also worthy of consideration when setting the rules in your Style Guide. The size used here is generally considered to be readable without effort for most people. A larger point size would be even easier, but would increase the page count of the document and have the likely effect of causing text on a single topic to run to more than a single page. Conversely, too small a point size reduces readability. In the extreme, a very small font size will discourage users from reading the document at all.

A final word on choice of fonts. Your company’s standards (or your client’s standards) may make the choice for you. Check the likely present and future requirements before finalising this part of your Style Guide.

Section 4 – Document structures

General

This section touches briefly on the structure of publications, in terms of chapterisation, use of annexes and appendices, etc.

Chapterisation

Breaking a large document into separate ‘blocks’ called chapters is familiar to everyone; just about every novel you care to take from a bookshelf consists of a number of chapters to make up the whole story. Why do authors do this? One answer is to break the whole into smaller ‘bite-sized’ chunks, making it less daunting to the casual reader, much as was mentioned earlier in this chapter when discussing paragraph breaks and line spacing.

Another reason for the technique is that it is a way of conveniently separating areas of the story. An example is the type of novel that tells parallel tales about different characters. The chapter break then forms a convenient point to end an episode about one character or scenario and begin the next episode about another character or scenario.

In technical publications, both of these purposes have some validity. The reader or end-user is less daunted by a series of clearly separate chapters than a hefty book which appears to be unbroken from first page to last, and can navigate more easily when chapterisation shortcuts the locating of wanted information.

However, probably the major reason for splitting up a technical publication in this way is for ease of navigation. End-users, who may be product users, maintainers, etc., will locate wanted information much faster if there are clear navigation points, or ‘landmarks’.

Chapter breaks are obvious landmarks, particularly in the type of publication, which utilises tabbed divider cards between chapters. Divider card tabs may be plain, numbered (or lettered), or even printed with the chapter title. Sometimes multi-coloured tabs are used as a further speed of access feature. The user of the publication can simply turn to (say) the red tab for the fault-finding chapter.

Other methods of highlighting chapter breaks include colour-coding the pages themselves, or applying a coloured strip down the outer edge of each page. In black and white documents, a similar scheme can be employed which uses ‘finger tabs’ giving the chapter number or title, printed on the outer edge of each page. The vertical position of the finger tab is different for each chapter, and staggered through the document just like a set of physical divider card tabs. Figure 6-2 shows all the tabs for a publication; you would of course see only one of them on any individual page.

	Overview

	Operation

	Repair

	Spares

	Index

Figure 6-2 Example of finger tabs for document navigation

Appendices and annexes

We have all seen publications with appendices or annexes after the main body of the document. Your Style Guide should not only define the numbering scheme to be used for them, but when they should/should not be used and what they should contain.

A suggested definition of an appendix is: ‘A repository for supplementary information that is needed by the reader, perhaps for reference purposes, but is not appropriate to include in the main body of the document’.

Typically, appendices may contain specifications, error messages, sample programs, practice exercises, training records, and similar.

Some Dos and Don’ts for your Style Guide:

Do begin each new appendix on a right-hand page
Do give each appendix a title and a number or letter (and make sure the Contents List includes them)
Do give the pages distinctive page numbers. As an example, the first three pages in Appendix A could be numbered: A-1, A-2, A-3
Do not be tempted to dump information into an appendix that is of no real use or interest to the reader, for example deeply technical information that a design engineer thinks should be included
Do not include the index in an appendix.

Sequence of information

If your Style Guide includes specification of one or more ‘standard’ publication types, it may be possible to stipulate the order or sequence of the information contained within a given manual type. Standardisation of chapter order in similar manuals produced will help end users.

When generating a specification, try to make the sequence logical for the intended end user. In User Guides for example, beginning with a ‘How to use this Guide’ before the main body of the document will help readers and give them added confidence. Although individual requirements will be project or product dependent, a typical breakdown for a User Guide might be:

Preliminary pages including contents, glossary, associated publications, section on safety, etc.
How to use this guide
Getting started
System/product description
Operation (basic)
Operation (advanced)
Troubleshooting guide
User maintenance
Index
Appendix: On-screen error messages

For a maintenance manual, aimed at a different end user, the corresponding information sequence might be:

Preliminary pages including contents, glossary, associated publications, section on safety, etc.
Introduction/overview
System description
Installation information
Fault-finding guide
Recommended test equipment
Adjustments, testing and repair
System drawings
Parts/spares lists
Appendix: Preventative maintenance schedules

Similar lists can be compiled for each type of publication to be covered by the Style Guide, customised to comply with the requirements and products of the organisation involved.

Flexibility of rules

Wherever possible, allow flexibility in the Style Guide rules. You may for example find that an individual manual requires the inclusion of very large, complex drawings that will not fit in the selected page format (even as foldouts) and would; if reduced, contain text information far too small to read. Obviously a different solution would be called for.

If the drawings could not be redrawn and split into several sheets, another possibility would be the use of associated binders with the large drawings, multi-folded to a final (say) A4 format. Alternatively, you may consider having an associated volume at (say) A3 format, to avoid handling problems for the maintainer, who may otherwise be struggling with the many flapping folds of drawings in hostile environments.

Section 5 – Illustrations and other graphics

General

It is undoubtedly true that good illustrations and graphics contribute enormously to the understanding of the content of a publication. Very few manuals would succeed without ‘pictures’. However, there has to be consistency of style, positioning, numbering, and so on, if the finished publication is to look good and to give maximum value to the user.

Where to use them?

In many publications, the first ‘picture’ encountered by the reader will be a Frontispiece illustration. Dependent on the subject matter contained, this could be a system block diagram, a photograph of the product, an illustration of the product, and so on. It is just as important with graphics as it is with the text to bear the end user in mind when determining the style of ‘picture’ to include.

As a general rule within a publication, match the style of Figures with the associated text. For example, a detailed system block diagram would be out of place in an introduction or overview chapter.

However, your Style Guide will be more likely to be specifying other factors, such as:

Position – usually as close as possible to associated text reference, centred between side margins
Size – including whether whole page only and/or in text
Numbering scheme – none, chapter-based or publication-based
Title styles and positions
For electronically produced figures, the software and version

For User Guides describing application software, it is increasingly the case that figures showing screen captures, and used to illustrate procedural information, are not titled or figure-numbered. You may wish to title or number them in the traditional way in your Style Guide.

You may also wish to specify that electronic drawing files are linked to the publication, but not embedded in it. This technique gives smaller text files that can be handled more easily.

Deciding on figure types

Just as with the Frontispiece discussed earlier, the subject of the publication will influence the choice of the most suitable type of figure to be specified in any instance.

For example, quoting an applications software User Guide again, it is less likely that this will use many complex line drawings. In this type of publication, you will want to see more screen captures, graphs and charts, simple algorithms and photographs.

A typical Maintenance or Repair Manual may in contrast require many schematics, exploded view illustrations, and in-text adjustment or setting figures. The maintainer will require the fine detail of illustration to effect maintenance and repair of the system or product.

It is common practice in such large and complex manuals to have the majority of the drawings grouped at the end of each chapter, in many cases as foldouts. This system overcomes frequent interruption to text flow that would result if the figures were placed close to the text reference. It also gives a finished manual that is easier to print and collate.

A repair manual often includes an illustrated parts list. Here again, exploded views will be used, annotated with item numbers cross-referenced to adjacent parts lists. Some illustrations may need to be repeated to always face the parts list page that includes the item numbers on the drawing.

All these factors can be considered when compiling the rules for figures in your Style Guide.

Some figures Dos and Don’ts:

Do keep styles and sizes consistent
Do position in-text figures close to the associated text
Don’t use a complex drawing reduced to the point where captions are unreadable

Section 6 – Style guide aspects for on-line documentation

On-line/paper differences

If your Style Guide is to include the specification of on-line documents, remember that:

On-line documents are displayed in an area that is smaller than a paper page, and has different proportions
Whereas most paper documents are ‘portrait’ format, monitor and TV screens have a ‘landscape’ orientation.
A standard monitor may typically display as few as 24 lines of 80 characters – about 320 words for a full screen of text. This is far less than a paper page, which may contain up to 60 lines of text.
One of the disadvantages of the on-line presentation of documents is that users tend to follow instructions blindly if they form part of a long procedure, but only a small section of it is visible on the screen. This means that navigation and landmarks are more important.
Tests have shown that most people prefer a document which has a width approximately 1.6 times its height. This may seem to conflict with the fact that most paper pages are taller than they are wide. However, we do usually view a two-page spread when looking at a paper document. Considering A4 pages as an example, a two-page spread has a landscape aspect ratio of 1.41 to 1.
Negative contrast (dark characters on a light background) has been found to reduce errors, to speed up work, to increase comprehension, and to improve reader comfort and legibility.
Resolution of even high-resolution screens is low compared to typically good quality laser-printed paper pages. Essentially, you cannot display on screen, graphics with features smaller than a single pixel.
Colour rendition on a screen may appear different, and may comprise a limited range of different colours on certain monitors.

Planning your screen layouts

Taking all these factors into account, you should design your screen styles to define what can and cannot be displayed, where on the screen area features will be positioned, and how they will be implemented. As a starting point, try to create a plan in a methodical way, considering points such as:

A list of what needs to be displayed; items may include:
Contents lists
Document title and other headings
Text and graphics
Navigation buttons or links, etc.
Organisation of groups of similar items and of relative priorities of displayed information. Consider use of ‘attention grabbers’ such as blinking text or different colours.

Layout of the display so that users can find wanted text and other information effectively and easily.

Having made a plan after considering these and any other factors, be prepared to revise your plan until you are satisfied it fully reflects your anticipated requirements.

Split screen systems

Some successful on-line documentation screen systems use a split screen, where the major part of the screen contains the document ‘window’, and the left side is a separate ‘window’ containing a fixed or scrolling contents list in the form of a permanently visible navigation aid.

Figure 6-3 shows a representation of just such a system, which helps overcome one of the major problems of on-screen documents – that of getting ‘lost’ in the middle of a document.

In the example depicted, the part of the publication in view is indicated automatically in the left segment of the screen by highlighting in the ‘contents list’.

You can specify the set-up so that by clicking onto a heading line in the left-hand part of the screen, the main screen view will take the user to that point in the document.

Some on-line Dos and Don’ts

Do design your layouts carefully; users should find the screens easy to use and restful to read.
Don’t go overboard with colours; just as proliferation of fonts in a paper document is confusing, too many different colours are also to be avoided on screen.
Do use ALL CAPITAL LETTERS sparingly; all upper-case words are slower to read by around a third, compared with the same words in lower-case.
Do keep line spacing sufficient to make reading strain-free, but avoid too much space, which limits the amount of text that can be viewed without scrolling.
Do try to keep line lengths short. Longer lines require more eye movement and can be tiring.
Don’t justify text. Just as for paper documents, unjustified or ‘ragged’ text is easier to read.
Don’t use "As shown above" or similar; this can irritate users who can’t instantly see the item referred to.
Do specify good Help and Find systems; easy navigation is vital in on-line documents.
Do include graphics wherever possible, but bear in mind the limitations of resolution on-screen.

Do remember that complex graphics, especially in colour, can increase file sizes dramatically, slowing down movement around the document. A ‘trick’ is to call up a graphic from a stored location, allowing the same graphic to be used several times without increasing file size.

Introduction

The equipment comprises a Main Unit, external interface accessories, and the application software, which defines the functional behaviour of the equipment.

Main Unit

The unit is configured for 19-inch rack mounting, and comprises a Main Unit with Plug-in Printed Circuit Boards (PCBs) in a full width card frame, in which the card front panels are forward-facing and are visible through a transparent dust cover forming the unit front panel.

Power Supplies are provided from a Switched Mode Power Supply (SMPS) contained within the Main Unit and mounted at the rear of the card frame.

Dual, thermostatically-controlled fans dissipate excess heat generated while the unit is operating.

Processor Unit

The Processor Unit housed within the card frame in the Main Unit contains the PCBs, plugged into the backplane, and

Figure 6-3 Typical split screen layout arrangement

Chapter 1 Overview

General

System Features

Hardware Options

Main Unit

PCBs

Software Options

Standard

Custom

Chapter 2 Description

Introduction

Main Unit

Processor Unit

PCBs

Power Supplies

Plug-ins

Expansion Slots

Chapter 3 Operation

Getting Started

Basic Operation

Advanced Operation

Supervisor Features

Chapter 4 Troubleshooting

General

Alarm Indications

Status LEDs

Error Messages

Power Supplies

Chapter 5 Maintenance

Preventative Maintenance

Corrective Maintenance

Section 7 – configuration control

Before you issue your Style Guide, plan in future amendments and revisions, and how you will ensure that:

You will know who has copies of the original issue
Every copy holder will be certain to receive any updates and that you will know they are received and incorporated.

The Style Guide should help ensure that all your publications are consistent in specified style aspects, but this goal will not be achieved unless all involved personnel work to it, and always have the latest issue.

The necessary measures and rules to ensure this happens can be built into the Style Guide itself.

Single-point control of the issue and distribution of the Style Guide will avoid the existence of uncontrolled, obsolete copies being used in error, creating out of step versions in circulation.

Signed acknowledgement of receipt of updates will help control issue status of copies. Spot inspections to follow up will detect misuse of the configuration control system, such as failing to incorporate received revision packs.