Summary TW Course (FINAL FINAL)

[Al Barten <barten -at- ORRQMS2 -dot- PSF -dot- LMCO -dot- COM>]

OK gang, THIS SHOULD DO IT!  Sorry for the gibberish that most of you 
received. (Those who think on-line is ready for the masses haven't used 
the system I'm using!!!)

Al

---------- Forwarded message ----------
Date: Wed, 10 Jul 96 07:55:44 EDT
From: Vickie Mitchell <mitchell -at- orrqms2 -dot- psf -dot- lmco -dot- com -dot- psf -dot- lmco -dot- com>
To: barten -at- orrqms2 -dot- psf -dot- lmco -dot- com

testing....

A survey of writing problems
If you were volunteering to take (or had to give) an introductory technical writing course, what 
are the 10 most important topics you would like to see covered? 

(What are the major stumbling blocks to clear writing that you've observed with yourself, your 
colleagues, or your students?)

? For context, what is your role in tech writing? 

? Any comments?

A survey of writing problems (continued)
* Analyze audience & writing requirements	12
* Write clearly	23
*	Organize your material	12
*	Visual considerations	7
  	Build the writer-editor partnership	3
	Other	6

Analyze audience & writing requirements
1.	If writer is very familiar with subject, beware not to overlook what audience needs
2.	Anticipate users? problems and provide solutions rather than descriptions (define what 
the user needs)
3.	Define
4.	Define who, and what critical information they need
5.	Don?t describe what the software does, tell the reader how to use it
6.	Forget all of your assumptions
7.	Identify and write to their level
8.	Know who they are and write to their level
9.	Tell them what they need to know (??don?t tell me (customer) how you built it or what 
the code contains, just tell me how this will make my job easier or faster)
10.	Write to your audience
11.	Define the purpose for the documentation (how-to, reference, introduction, etc.)
12.	Define the purpose of the document:  understand it and stick to it

Write clearly
1. 	Ask for help in clarification
2. 	Avoid jargon
3. 	Keep writing simple:  fewer words make reading easier
4. 	KISS
5. 	KISS
6. 	KISS principle
7. 	Repeat information rather than provide cross-references
8. 	Sentences:  Avoid run-on sentences
9. 	Sentences:  Avoid run-ons
10. 	Sentences:  Keep them short
11. 	Sentences:  Subject and verb agreement
12. 	Sentences:  Use tense correctly
13.	Sentences:  Write short, single-topic sentences; avoid run-on sentences
14.	Sentences:  (Discuss examples before & after rewrites; emphasize right & wrong way to 
arrange; how to begin & end)
15.	The importance of clear writing:  why technical editing is not just ?making it look 
pretty?
16.	Use grammar correctly
17.	Voice:  Correct use of active & passive
18.	Voice:  Eliminate passive constructions
19.	Voice:  Use active and passive voices correctly
20.	Voice:  Use active voice
21.	Write clearly
22.	Use standards
	a)	Agree on them; comply with specifications
	b)	Style guide;  define nomenclature at the start of your project and keep it 
consistent
	c)	Style guides, especially in-house, including templates, application tools, who 
to call
	d)	Terminology:  use terms consistently (example:  Don?t call something a ?user 	
interface? in one paragraph and ?GUI? in another.)
	e)	Use change control procedures
23. Make your writing more readable
	a)	Acronyms & abbreviations:  try not to use them. If you must use them, 
	define them.
	b)	Acronyms:  follow rules (spell out on first appearance, repeat each 
	chapter, except common ones)
	c)	Acronyms:  spell out the first time they?re used in each chapter
	d)	Mechanics:  Avoid comma splices 
	e)	Mechanics:  Don?t use initial capitals on every word. Learn how to 
	determine whether something is really a proper noun
	f) 	Mechanics:  Hyphenate compound adjectives
	g)	Mechanics:  Run your spell-checker
	h)	Agree on them; comply with specifications

Organize your material
1.	Organization
2.	Organization:  Identify task order
3.	Organization:  Organize your document logically
4.	Organize information:  Chunk, use organizing schemes
5. 	Index:  Make it useful
6. 	Index:  Provide multiple ways to find information
7. 	Index:  Spend quality time on it
8. 	Make information easy to find
9. 	Provide a useful table of contents
10. 	Provide glossary
11.	Provide glossary if necessary
12. 	Test for usability 

Visual considerations
1.	Format:  Keep conventions consistent 
(house style guide helps here!)
2.	Format & style:  define best (easiest accessibility)
3.	Graphics:  Remember that a picture is worth 1000 words (figures, tables, pictures, etc.)
4.	Graphics:  Use lots of pictures and explain them
5.	Use bullets & numbered steps
6.	Use tables, figures, illustrations, diagrams, flowcharts, etc.
7.	Write useful headings

Build the writer-editor partnership
1.	Fortify writer-editor relationship

2.	Don?t sweat the redlines!  Technical writer or editor is not impugning your intelligence 
when correcting your grammar?this is especially important for those who learned English as a 
second language.

3.	Seek feedback and incorporate it.

3.	Confidence in writing comes from understanding language basics.

Other
1.	Language:  Use gender-neutral language
2.	Accuracy:  Proofread & review
3.	Accuracy:  Test for functional accuracy 
4.	Practice paragraph rewrites (discuss examples before & after rewrites)
5.	Prepare to write (importance of reading good writing; keep notebook & take notes in 
meetings; get early start on your project)
6.	Prepare to write:  Don?t put off your projects until the last moment. 
		Assume your first draft will be awful!
		This will allow time for REWRITING.
		There are no finished projects only deadlines.

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-