Conventions of Technical Documents Scott Hale ENGL 3153 Technical Writing.

Conventions of Technical Conventions of Technical DocumentsDocuments

Scott HaleScott Hale

ENGL 3153ENGL 3153

Technical WritingTechnical Writing

Technical DocumentsTechnical Documents Designed differently than other kinds of Designed differently than other kinds of

documentsdocuments– Doesn’t use unbroken sequences of words, Doesn’t use unbroken sequences of words,

sentences and paragraphssentences and paragraphs– Instead uses charts, diagrams, lists, Instead uses charts, diagrams, lists,

varying fonts/sizes, headings, and other varying fonts/sizes, headings, and other aides to assist document navigationaides to assist document navigation

Technical Documents Technical Documents Con’t...Con’t...

Rarely receive audiences undivided Rarely receive audiences undivided attentionattention– Readers skim to discern relevant Readers skim to discern relevant

informationinformation– Audience should be able to leave a portion Audience should be able to leave a portion

of the document and return to it quicklyof the document and return to it quickly

Technical Documents Technical Documents Con’t...Con’t...

Audience doesn’t read document as Audience doesn’t read document as leisurely activityleisurely activity– They read it because they have toThey read it because they have to– Will use the easiest methodWill use the easiest method

Technical Documents Technical Documents Con’t...Con’t...

With the rapid proliferation of With the rapid proliferation of documentsdocuments– Your document will compete for your Your document will compete for your

audience’s attentionaudience’s attention

As a Technical Writer...As a Technical Writer...

Your goal is to make information access Your goal is to make information access and retrieval as easy as possibleand retrieval as easy as possible

Create a USABLE and SCANNABLE Create a USABLE and SCANNABLE documentdocument

Creating a Usable Creating a Usable Document DesignDocument Design

Shape each pageShape each page– Consider look, feel, and the overall layoutConsider look, feel, and the overall layout

Paper and InkPaper and Ink Routine DocumentsRoutine Documents

– Black ink on 8 1/2”x11” low-gloss, rag-Black ink on 8 1/2”x11” low-gloss, rag-bond, white paperbond, white paper

Published DocumentsPublished Documents– Dependant on cost and audience, you may Dependant on cost and audience, you may

want coated, glossy, heavier paperwant coated, glossy, heavier paper

Type or Print Quality Type or Print Quality Print from laser or ink-jet printerPrint from laser or ink-jet printer If ink-jet, use special coated paperIf ink-jet, use special coated paper

Page NumbersPage Numbers

Use lower-case roman numerals(I, ii, iv, Use lower-case roman numerals(I, ii, iv, xxv) for title page, table of contents, xxv) for title page, table of contents, prefaces, and abstractsprefaces, and abstracts

Use arabic numerals (1, 2, 15, 38) for all Use arabic numerals (1, 2, 15, 38) for all subsequent pagessubsequent pages

Headers and FootersHeaders and Footers

Signal a change in information or Signal a change in information or importanceimportance

Usually offset with a larger, bolder Usually offset with a larger, bolder font/sizefont/size

White SpaceWhite Space

The space on a page NOT filled by The space on a page NOT filled by text/imagestext/images

Divides the document into small, Divides the document into small, digestable groups of related informationdigestable groups of related information

Separates sections, headings, tables, Separates sections, headings, tables, and images from text/paragraphsand images from text/paragraphs

Intended to improve document Intended to improve document appearance, clarity, and emphasisappearance, clarity, and emphasis

MarginsMargins

JustifiedJustified– Even right margin creates channels of white Even right margin creates channels of white

space and can be more difficult to readspace and can be more difficult to read Used for formal documents: books, annual Used for formal documents: books, annual

reports, etc.reports, etc.

UnjustifiedUnjustified– Uneven right margins can be easier to readUneven right margins can be easier to read

Used for less formal documents: memos, letters, Used for less formal documents: memos, letters, in-house reports, etc.in-house reports, etc.

Line LengthLine Length

Too long lines tire your eyes, annoy Too long lines tire your eyes, annoy readerreader

Too short lines disrupt rhythm of Too short lines disrupt rhythm of reading, annoy readerreading, annoy reader

Ideal is sixty to seventy (60-70) Ideal is sixty to seventy (60-70) characters per linecharacters per line– Nine-twelve (9-12) words per lineNine-twelve (9-12) words per line

ColumnsColumns

Two-columns often used for newsletters Two-columns often used for newsletters and brochuresand brochures

Single-columns work best for Single-columns work best for complex/specialized informationcomplex/specialized information

Line SpacingLine Spacing

For documents that will be read in their For documents that will be read in their entirety (memos, letters, etc.), use single-entirety (memos, letters, etc.), use single-spacing in paragraphs and double-spacing spacing in paragraphs and double-spacing between them, with no indentationbetween them, with no indentation

For longer, selectively read documents For longer, selectively read documents (reports, proposals, etc.), increase line (reports, proposals, etc.), increase line spacing within and between paragraphs, spacing within and between paragraphs, providing indentationproviding indentation

Tailor Made ParagraphsTailor Made Paragraphs

Use long paragraphs for clustering closely-Use long paragraphs for clustering closely-related materialrelated material

Use short paragraphs for making complex Use short paragraphs for making complex material more digestable, giving step-by-step material more digestable, giving step-by-step instructions, or emphasizing vital informationinstructions, or emphasizing vital information

Don’t indent, but separate short paragraphs Don’t indent, but separate short paragraphs with spacingwith spacing

Avoid ‘Orphan’ lines of paragraphsAvoid ‘Orphan’ lines of paragraphs

Stacked ListsStacked Lists

Readers prefer lists to paragraphsReaders prefer lists to paragraphs List the followingList the following

– Advice or examplesAdvice or examples– Conclusions and recommendationsConclusions and recommendations– Criteria for evaluationCriteria for evaluation– Errors to avoidErrors to avoid– Materials/equipment for proceduresMaterials/equipment for procedures– Parts of a mechanismParts of a mechanism– Steps in a sequenceSteps in a sequence

Stacked Lists Con’t…Stacked Lists Con’t…

Usually requires no punctuation, unless Usually requires no punctuation, unless a list of sentences or questionsa list of sentences or questions

Set off with a visual aidSet off with a visual aid– Numbers for order of importanceNumbers for order of importance– Bullets, dashes, or asterisks for non-order Bullets, dashes, or asterisks for non-order

of importanceof importance– Open boxes for checklistsOpen boxes for checklists

Introduce list with an explanationIntroduce list with an explanation

FontsFonts

Have/create “personality”Have/create “personality” For technical documents, use a For technical documents, use a

conservative font, conservative font, unlike thisunlike this SerifsSerifs vs. Non-serifs vs. Non-serifs Size is important...Size is important... BoldBold, , underlineunderline, normal, , normal, italic, italic, SMALLL CAPSSMALLL CAPS

CAPITALS vs. lower-caseCAPITALS vs. lower-case Big to small, Dark to lightBig to small, Dark to light

HighlightingHighlighting

Used for emphasisUsed for emphasis Fonts size/style, white space, etc. Fonts size/style, white space, etc. Horizontal (un/broken) lines to separate Horizontal (un/broken) lines to separate

sections or offset warningssections or offset warnings Not all highlighting is equal…Not all highlighting is equal…

Highlighting Con’t…Highlighting Con’t…

BoldfaceBoldface for single sentence/brief for single sentence/brief statementstatement

ItalicsItalics for words, phrases, but not multiple for words, phrases, but not multiple lineslines

SMALL CAPSSMALL CAPS for headings and short for headings and short phrasesphrases

Small type sizesSmall type sizes for captions and labels for captions and labels

Large type sizesLarge type sizes used sparingly used sparingly

HeadingsHeadings

Used for document access and orientationUsed for document access and orientation InformativeInformative Specific, yet comprehensiveSpecific, yet comprehensive Grammatically consistentGrammatically consistent Visually consistentVisually consistent Four levels of heading: Title, Main, Four levels of heading: Title, Main,

Secondary, TertiarySecondary, Tertiary