© M. Reber 5/19/2015 Why Details Matter in Technical Writing Little things that make a big difference.

© M. Reber 04/18/23

Why Details Matter in Technical Writing

Little things that make a big difference

Why Do I Insist Details Matter?

I’m Anal Retentive? I’m Too Picky? It’s My Personal Opinion? I’m a Hard Teacher? I Want to Make You Miserable? I’m Just Making up Stuff?

2

The Answer Is…

NONE OF THE ABOVE!!!

3

Details Matter Everywhere!

Programming JavaScript Updating Financial Reports Baking a Cake Jumping a Dead Car Battery Preventing Computer Viruses

4

Programming JavaScript

If you leave a “}” or a “=“ out of a script…

<script language="javascript" type="text/javascript"><!—

function popitup(url) {newwindow=window.open(url,'name','height=200,width=150');if (window.focus) {newwindow.focus()}return false;}var newwindow = '';function popitup(url) {// --></script>

5

Programming JavaScript (cont.)

You might see this…

6

7

Programming JavaScript (cont.)

Instead of this:

8

Updating Financial Reports

If you place decimals incorrectly…

12.11

1.211

121.1-------------

Updating Financial Reports (cont.)

You might see this…

12.111.211121.1------------- 134.421

9

Updating Financial Reports (cont.)

Instead of this:

12.1112.1112.11------------- 36.33

10

Baking a Cake

If you add 1t of baking powder instead of 1T in a recipe… Amaretto Sponge Cake

11

Ingredients:

3 tablespoons butter or margarine 1T baking powder 1 large egg 1/4 cup all-purpose flour 3 (8-ounce) packages cream cheese 3/4 cup granulated sugar 3 tablespoons all-purpose flour 3 large eggs 1/4 cup amaretto liqueur

Baking a Cake (cont.)

You might get this…

12

Baking a Cake (cont.)

Instead of this:

13

Jumping a Dead Car Battery

If you clamp the red (+) cable onto the black (-) post...

14

Jumping a Dead Car Battery (cont.)

You might get this…

15

Jumping a Dead Car Battery (cont.)

Instead of this:

16

Preventing Computer Problems

If you forget to protect your hard drive… Scan for viruses Turn your firewall off Give out your password Open suspicious e-mails Let dust build up in the vents

17

Preventing Computer Problems (cont.)

You might get this…

18

Preventing Computer Problems (cont.)

Instead of this:

19

So What Did We Learn?

Every discipline has rules!!!

20

What Kinds of Detail Matter in Technical Writing? Accuracy of Information Consistency Formatting Styles Graphics

21

Accuracy of Information

Ensure the steps or procedures in a process are in an exact order.

Ensure the system you describe works the way you say it does.

Ensure the information you share is well researched.

22

Consistency

Consistency is a critical concept in writing, especially technical writing. Consistency of naming conventions Consistency of formatting & style

Inconsistency can confuse your reader.

23

Consistency (cont.)

Examples of inconsistent naming conventions:

24

email E-mail Email Internet net Web site website

Print dialog box Print Screen PrtScrn Thumbnail Icon

an item A 2nd item A third item. item 4 Item #5

Consistency (cont.)

Examples of consistent and inconsistent formatting & styles:

25

Heading 1 Heading 2

Body text

Heading 1 Heading 2

Body text

Heading 1 Heading 2

Body text Heading 4

Body text Heading 3

Body text Heading 3

Consistent Inconsistent

Formatting

Formatting creates: Distinct styles for each element of your document.

Formatting keeps: Style elements consistent throughout a document.

Formatting establishes: A relationship between subject.

26

Formatting (cont.)

Formatting elements include: Headings (H1) and Subheadings (H2) Body Text Bulleted Lists Tables Headers and Footers White Space “Note!”, “Caution!” or “Warning!” Boxes

27

Styles: Personal Style

Style: noun [stahyl]: Style is a particular, distinctive, or

characteristic mode of action, appearance or manner of acting.

28

Styles: Personal Style (cont.)

Compare this style…

29

Styles: Personal Style (cont.)

…to this style.

30

Styles: Personal Style (cont.)

Just as physical attributes and mode of dress give a person a different look, feel or image…

31

Styles: Text and Typeface

…dressing up your text gives it a different look, feel or image. Bold it Italicize it Give it some …….. space Give it some COLOR Differentiate your text levels:

Headline Level 1Headline Level 2

Headline Level 3Body Text

Use Microsoft Word to help you define common text styles that create your distinctive design.

32

Styles: Microsoft Word Styles

Are a set of stored formatting commands you can use repeatedly throughout a document For example, you can define a style for headings that is

left-justified, bold, blue, 18 pt. font, with a 1.5 border With a mouse click, you can apply formatting characteristics to

selected text all at once instead of one at a time

Used to “tag” or identify parts of a document You can create unique styles for each type of text in a document

(headings, body text, captions, etc.) You can easily revise a style and automatically update all

occurrences of that style throughout a document

Allow you to customize the look/layout of a document33

Styles: Writing Style

Your unique writing style is defined by: The way you use metaphorical expression, words,

grammar and punctuation, etc.

But in the corporate environment, your writing style must mesh with others by: Modifying your personal style to match your

company’s style guide conventions and corporate image.

Writing in the corporate voice using standard abbreviations, verbiage, and term usage.

34

Graphics

Just as text and writing styles make your document unique, graphics alter its mood and appearance.

Graphics can: Give a specific, consistent look to your document Break up the monotony of straight text Emphasize important information Appeal to right-brained users Convey quantitative relationships (percentile rankings,

trends, etc.) Communicate internationally

35

Graphics (cont.)

Use graphics to: Show how something looks or is constructed Show how to do something Explain how a process works Show how something is organized Help the reader find specific facts Show relationships Make a persuasive point

36

Not to beat a dead horse but...

37

Details…

DO MATTER!!!

38