Summary TW Course (Resend)

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

My first attempt at attaching a file was, I suspect, a failure. This
should work better.

A while back a colleague of mine asked me to survey the group with the
following question:

"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?"

She organized the responses by category and listed the individual
responses in what should be the attachment below.

Once again, thanks to everyone who responded.

Al Barten (and Vickie Mitchell)



Summary of Responses to Survey Question



Original question

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?

---------------------------------------------------------------------------------------------------------------------------

Number of answers by category

*	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.