TCMG 272 CH 3

Document Planning

(starts with determining the characteristics of the audience) -Who is the target audience? -What does the audience already know? -What does the audience need to know? -What do you want the audience to be able to do when they finish the reading document? -What medium will be used to transmit the document to its audience?

Technical Writing Style

- use short declarative sentences, brief phrases, and lists -starts with the most important point at the beginning of a section -communicate in order -step by step sequence of events -info should be concise but not cryptic -dont' use humor -writer's personal preference should be clearly labeled; readers should be quickly able to identify sources of bias

Technical Writing Strategies

-Analogies -Repetition (for emphasis and to help reader recall the material later) -Consistent word use (don't use synonyms, consistency can contribute to a reader's understanding) -parallel structure consistent verb use

common technical writing problems

-clutter -inappropriate typefaces -gender references -unclear referents -passive voice -nominalization -wordiness -jargon -undefined acronyms and initialisms (you have to define them) -idioms -dangling phrases

The Technical Writing Process

1. Generate a list of important ideas or features to be covered 2. Organize the idea list into a logical, hierarchical sequence to form an outline 3. Expand the outline into a first draft 4. Edit the draft one or more times to clarify 5. Arrange for an outside review of the document 6. Revise the draft into its final form 7. Proofread the final document

Simple Sentence

Contains one subject, one verb, expresses one complete idea

Active voice

Good technical writing uses this voice with it the subject of a sentence performs the action indicated by the ver "avoid touching the surface of the optical media"

Email, Chat, and Text Messages

May seem informal should reflect good technical writing skills provides opportunity to review/revise response before sending avoid use of abbreviations

What do you want the audience to be able to do?

Medium that will be used to transmit a document to its audience should be determined before the document is written EX: print format, online formats, mobile format online documents should be shorter but can include hyperlinks mobile format should be divided into very short segments

Step 1: Generate an Idea List

Part of the Technical Writing Process You need to brainstorm exclude nothing

Organization of technical documents

Sequentially or Hierarchically

Troubleshooting Guides

To help coworkers and clients solve problems common examples -problem solving chapter in a user guide -FAQ page for a website -user support script to handle specific type of problem incident -problem report and solution in a help desk knowledge base Must be clear, concise, and well written

Ball

What is life

Introduction

What will I learn from this document? Is this document intended for me?? Why would anyone want to read this?

Analogy

a comparison between an unfamiliar concept and a familiar one it highlights the similarities between things

Referent

a concrete word or concept that is designated by another word words such as this, that, it, they The cat and the dog both are animals. They are good examples of what a feline is. They is unclear as to which it is referring to because previous sentence has two nouns

Idiom

a word or phrase whose meaning is different from the literal meaning of the separate words in the phrase "does the trick" means "works"

initialism

an abbreviation formed from the initial letters of words in a phrase; pronounced using the individual letters in the abbreviation USB - universal serial bus

dangling phrase

an expression at the beginning or end of a sentence that adds little to the meaning and only makes the sentence longer - As an employee in this company, my email inbox is overflowing -my employee email is overflowing

Documentation

any form of written communication intended to provide user support information to end users or coworkers.

What does the audience already know?

attempt to learn about the readers' background make a statement in the intro about what the writer assumes readers already know may be done using a questionnaire always cover basic skills first EX: "the info in this reference sheets is for PowerPoint users who have a basic understanding of presentation software concepts and need a reference tool for the most frequently used features in PowerPoint"

Common types of documentation

brochures and flyers newsletters handouts and training aids user guides, handbooks, and manuals online help systems email, chat, and text messages webpages proposals, letters and memos procedural and operational documentation troubleshooting guides

Online Help systems

common features in application software sometimes supplied on CDs or DVDs; customers can use for self training sometimes embedded into application can sometimes replace printed manuals as a source of information also has formatted versions for users on mobile devices

four criteria used to evaluate a technical document

content, organization, format, and mechanics

What does the audience need to know?

critical step in technical writing; helps a writer define the purpose of the document Need to know in order to move readers from what they already know to what they need to know EX: "steps below will hep la new GPS Navigation user to download and install an updated version of maps and data into their GPS device"

Sans serif typefaces

do not have serifs; often used for titles and headings

brainstorm

done to identify as many topics as you can think of that might be useful

justified text

falls under clutter when text is aligned at both right and left margins, adds extra spaces between words so sentences are the same length

Hierarchical Organization

flows from top to bottom info is arranged from general to specific -online help systems

Sequential Organization

follows a step by step approach info is arranged in the order in which the steps are executed -procedural documents

tutorial format

guides user step by step through the features of a technology with frequently used features covered first convenient for new users because it emphasizes natural sequence of learning each step

Style elements

help readers understand the structure of the document

Who is the target audience?

helps pinpoint the readers level of technical expertise; Determine their reading level

hyperlink

highlighted word or phrase in a document, which when clicked, takes the user to additional information about the word or phrase by displaying different webpage, opening word document, jumping to another location on current page or opening popup window

serif typefaces

include serifs, which are fine lines that project from the top and bottom of a font's letters; these lines lead the eye from letter to letter across the line improving readability used for body text

Procedural and Operational Documentation

include steps to follow and checklists intended for internal user technical writing skills essential

Body of a written work

includes explanatory material explanation followed by a detailed description of the sequential steps necessary to perform a task briefly describe common problems users are likely to encounter and how to recover from them

Specialty typefaces

intended for special documents; such as invitations, brochures, or flyers interesting and fun informal

troubleshooters

interactive help systems

Nominalizatoin

is the use of -tion, -ing, -ment and other word endings to create nouns out of verbs avoid in general; verbs are easier to understand develop better than development

Style sheet

lists an organizations preferences for common terms so all writers use consistent terminology can also be a lengthy document that also lists preferred grammatical structures, product name usage conventions

format consistency check

makes sure that the fonts of heading and subheadings, indentation, centering, boldface, italics, and underlining are used consistency throughout the document (do not overuse; they shouldn't be a distraction to the reader)

user guides, handbooks, manuals

more formal example of written documentation designed to supplement vendor documentation and trade books w/info specific to an organization or computer facility

proposals, letters, memos

needs assessments for departments or individual users need to be in this format also used to send to colleagues and supervisors basic user support communication skill

webpages

organized for quick location of information material should be short; with hyperlinks that lead to additional information web based material must be well written, accurate, and up to date

Step 2: Organize the Idea List into an Outline

part of the technical writing process -Organize into a logical order flexibility is important during try different sequence of ideas as this happens other topics might come to mind that can be added most important question it answers is "In what order does the reader need to know this information"

Step 4: Edit the Draft

part of the technical writing process -edit your previous work -more than once recommended - a single edit pass rarely catches all the different writing problems -first edit pass used to delete extra words; tighter writing takes less time to read -second edit; format consistency check -third edit; technical accuracy check (quality assurance pass)

Step 3: Expand the Outline into a First Draft

part of the technical writing process created after creating the initial outline when preparing; -organize paragraphs with topic sentences number of paragraphs on a page should be small -Use transitional words and phrases such as "for example" "therefore" and "as a result" it helps readers keep track of where they are in a sequential organization -Define Terms clearly and boldface them where they are defined -use format features such as different sized headings, italics for emphasis, bulleted or numbered lists -Format consistency; use a consistent format of headings, paragraphs, and tables -Lists and Tables

Step 6: Revise the Draft

part of the technical writing process done in order to incorporate suggestions and corrections when your revisions make improvements that are only marginal and don't significantly enhance the readability or accuracy of the document then its time to stop reviewing and revising

Step 5: Get an Outside Review

part of the technical writing process is like a beta test of a new product a reviewer can spot inconsistencies or find unclear meanings

Step 7: Proofread the Document

part of the technical writing process proofread one last time to make sure no small errors remain can be done by a professional proofreader, copyeditor, or a colleague

newsletters

popular in large organizations where support staff does not come in direct contact with most employees on regular basis

How you access Windows help system

press windows keyboard button then press F1 enter troubleshooter in search box click link for troubleshooter you are interested in OR click troubleshooting link in windows control panel

handouts and training aids

primarily intended to summarize and promote recall of material covered in a training session / may be available at a library of frequently asked questions usually short/ address single topic

brochures/flyers

primarily promotional and intended to catch readers eye and "sell" the event

reference format

pulls together all the information on a specific topic in a single page, section, or chapter for experienced users

10th - 12th grade level

reading level for documents intended for a technical audience

8th or 9th grade level

reading level to strive for in computer documents targeted at an audience of general users

Summary of a written work

should be brief review of the main points and results achieved direct readers to additional information

Sifo-Dyas

the Jedi who ordered the creation of the Clone Army in secret

Passive voice

the subject of a sentence receives the action indicated by the verb "touching the optical media surface should be avoided"

How is technical writing different from other writing

the type of information communicated as well as the goals, style, and organization of the documents

Acronym

word formed from the initial letters of words in a phrase RAM - random access memory

Jargon

words understood only by those experienced in a field

technical accuracy check

writer tests any procedural or technical steep in a document by performing the steps with the technology used to eliminate errors in step by step instructions

Parallel structure

writing strategy in which similar items in a sentence, list, or table are treated consistently EX: use of consistent verb tenses and parts of speech