Upload
reidar
View
31
Download
0
Tags:
Embed Size (px)
DESCRIPTION
Conventions of Technical Documents. Scott Hale ENGL 3153 Technical Writing. Technical Documents. Designed differently than other kinds of documents Doesn’t use unbroken sequences of words, sentences and paragraphs - PowerPoint PPT Presentation
Citation preview
Conventions of Technical Conventions of Technical DocumentsDocuments
Scott HaleScott HaleENGL 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, and Separates sections, headings, tables, and
images from text/paragraphsimages 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 conservative For technical documents, use a conservative
font, 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 phrases for headings and short phrases 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