© m. reber 5/19/2015 why details matter in technical writing little things that make a big...
TRANSCRIPT
© 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
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
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
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
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.)
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