ENC 4260, Advanced Technical Writing Structure and Design

in Technical Documents

Week 7 • Spring 2015USF Sarasota-Manatee

Length of this lecture audio (13 slides) = 00:24:49Jot down the three audio codes and the numbers of the slides where they are mentioned.

Send the Week 5, 6, and 7 codes with Assignment 3, due by Feb. 23, 2015. at 6 p.m.

© 2015 by T. E. Roberts, Instructor

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 2 of 13

Week 7 Agenda

• Basic rules of organization

• A-B-C Format (Abstract, Body, Conclusion)

• Design guidelines

• Design and content work as partners to serve your reader

• Assignment 3 reminders

This lecture owes a debt to Pocket Guide to Technical Communications, Chapter 2, and Kaplan Technical Writing, Chapter 6 (pages 105-120), as well as various sources in print, on the internet, and the instructor’s own experience.

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 3 of 13

Basic Rules of Organization

1: Different parts for different readers• Document should be aimed at a specific class of reader but

readable by every decision maker• Abstract (introduction/summary) concisely expresses main

message

2: Emphasize beginnings and endings• Most readers are in a hurry and thus need key messages clearly

stated at opening and closing of sections• Information (as in a technical document) differs greatly from

entertainment (novel, movie, video, poem, memoir, intellectual musings)

• Your document needs a clear objective and a way to assess results

3: Repeat key points• Readers may not read sequentially from beginning to end• Repetition will not only reinforce a message but also make it

visible again and again throughout your document• Repetition and repetitiousness are not the same!

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 4 of 13

A-B-C Format• Abstract: The big picture

• Introduction (What’s the purpose of the document?)• Summary (What are the key points?)• Scope (Size of project, process, application, and so on)• Contents (List the sections to follow)

• Body: Supporting Details• Background (What led to this report or document?)• Methods (How was information collected and analyzed?)• Data (Specific evidence, analysis, proof, features and benefits)

• Conclusion: Wrap-Up, Recommendations• Results (Conclusions from research and analysis)• Action steps (What should the reader do with this information?)• Emphasis (What is the single most important message?)• Future follow-up (Where to find additional information?)

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 5 of 13

Design Guidelines

1: Use white space liberally

2: Use headings and subheadings for clarity

3: Use lists frequently but meaningfully

4: When appropriate, eye-catching titles can generate interest

• “Five Injuries Common in Ill-Equipped Labs”• “Six Reasons for Mastering PhotoShop”• “Three Often-Neglected User Documents”

5: Use fonts effectively

PAGE DESIGN PRINCIPLES APPLY TO BOTH PAPERAND ELECTRONIC MEDIA

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 6 of 13

Design Guidelines (cont.)

1: Use white space liberally

• Crowded content is hard to read

• Extra spacing shows attention to design quality

• Effective page layout improves reader understanding

• Space costs nothing extra in electronic documents

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 7 of 13

Design Guidelines (cont.)

2: Use headings and subheadings for clarity

• Use at least two subheadings under a main heading(“divide” < di- means “two”)

• Maintain parallel grammatical construction (e.g., verbs or nouns, but not a mix of the two) (note use of parallel imperative verbs on this slide: USE, MAINTAIN, PLACE, KEEP, APPLY)

• Place at least one heading/subheading on each page of text to provide the reader a visual break and easy scanning

• Keep paragraphs short -- scannable chunks rather than big blocks of text

• Apply consistent format for headings (MS Word makes this easy through STYLE command)

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 8 of 13

Design Guidelines (continued)

3: Use lists frequently but meaningfully

• Use no more than five items at a time (a limit of three is even better)

• Apply bullets, numbers, and indentation consistently & logically

• Punctuate, space, and capitalize lists properly

• Create proper lead-in and parallel structure

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 9 of 13

Design Guidelines (continued)

4. When appropriate, eye-catching titles can generate interest

• While only a small part of the physical design, the wording in titles, heads, and subheads may have a major impact on reader’s understanding

• The composition of titles and heads benefits from experience, creativity, and sharp understanding of content

• This is a specialized job at some publications such as newspapers

• Although not emphasized for technical communication, strong titles and heads can strengthen a document -- the following tips may be helpful:

http://www.copyblogger.com/magnetic-headlines/

http://web.ku.edu/~edit/heads.html

http://econsultancy.com/blog/63106-10-bitchin-tips-for-writing-irresistible-headlines

http://www.wikihow.com/Create-Technical-Writing-Headlines

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 10 of 13

Design Guidelines (cont.)

5: Use fonts effectively

• Apply mix of serif and sans-serif for headings and body copy (some believe serif is easier to read for body copy)

• SERIF (example: Times Roman) = abcdefghijklmnopqrstuvwxyz1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ

• SANS SERIF (example: Arial) = abcdefghijklmnopqrstuvwxyz1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ

• Stick with just two fonts in a document (excessive variety of fonts marks you as an amateur who has just discovered the “font” command on his or her computer!)

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 11 of 13

Design + Content Partnership

• How you say something cannot be conceptually separated from what you are saying

• Readers of technical documents are also often writers of such documents and thus may be more demanding than general readers

• “The medium is the message.” (Marshall McLuhan, 1964)

• “We affect what we observe by the mere act of observation.” (principles of phenomenology)

• Ultimate standard of clarity and impact is the reader’s perception, not the writer’s intention ... writers who think they are “superior” to the reader will fail (see this advice on “how to read a technical document”: http://www.wikihow.com/Read-Technical-Writing)

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 12 of 13

Document Samples

See also this prize-winning example: Florida Turnpike 2007 Annual Report

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 13 of 13

Format & Content in Assignment 3

• Option 1: Analytical Essay• Use standard format shown

on page 15 of syllabus• See student sample on

website• Use headings and

subheadings toguide the reader

• Use call-outs if appropriate

• Option 2: Technical Proposal• See sample on website for

format and content • Remember that this is a

SELLING document

This box with lavender background is an example of a CALL-OUT. It may be used to emphasize a brief quotation or similar statement that sums up an important aspect of your message and thus deserves extra attention. Read MS Word Help instructions on how to position and format a text box on the page. (Use the call-out sparingly or it will be ignored!)

ENC 4260, Advanced Technical Writing • Spring 2015 • Week 7 • Slide 14 of 13

Assignment 3 Reminders

• Send to me by Monday, Feb. 23, 2015, 6:00 p.m.• Name your file and email subject this way:

• Lastname_4260_3_markup.docx (if you want a detailed review and are willing to return a full revision within a week)

• Lastname_4260_3.docx (if you want just a grade posted to Canvas)

• Apply assignment & formatting directions and USAGE TIPS in syllabus carefully before completing your work

• Include lecture codes for Weeks 5, 6, and 7 in the body of your email (indicate specific slide numbers)

• Begin thinking about Assignment 4• See directions in syllabus and choose a topic• Prepare outline for submission by Monday, March 9, 2015, 6 p.m.• I will introduce Assignment 4 in the Week 8 lecture