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