Summary: TW Course

Subject: Summary: TW Course
From: Al Barten <barten -at- ORRQMS2 -dot- PSF -dot- LMCO -dot- COM>
Date: Wed, 10 Jul 1996 07:37:43 -0400

A while back I asked for a colleague:

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

My colleague thanks the group for your quick and helpful responses. She
organized them into six general categories (below) and listed all the
individual responses for each category in the attached file.

Categories and number of responses:

Analyze audience & writing requirements 12
Write clearly 23
Organize your material 12
Visual considerations 7
Build the writer-editor partnership 3
Other 6

Thanks from both of us. This group is always helpful!

Al Barten (and Vickie Mitchell)
Tech Writers
Lockheed Martin Defense Systems
Pittsfield, MA

{\rtf1\ansi \deff4\deflang1033{\fonttbl{\f4\froman\fcharset0\fprq2 Times New Roman;}{\f5\fswiss\fcharset0\fprq2 Arial;}{\f9\fswiss\fcharset0\fprq2 Helvetica;}}{\colortbl;\red0\green0\blue0;\red0\green0\blue255;

\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;\red128\green0\blue0;

\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}{\stylesheet{\f4\fs20 \snext0 Normal;}{\s1\tqr\tx11880 \b\i\f9\fs16 \sbasedon0\snext0 heading 1;}{\s2\fi-180\li180 \b\i\f9\fs14 \sbasedon0\snext0 heading 2;}{\*\cs10 \additive

Default Paragraph Font;}{\s15\fi-720\li720 \f4\fs22 \sbasedon0\snext15 Style1;}{\s16 \b\i\f5\fs28\lang1024 \snext16 Head1;}}{\info{\title A survey of writing problems}{\author Field Documentation & Training}{\operator Field Documentation & Training}

{\creatim\yr1996\mo7\dy9\hr15\min1}{\revtim\yr1996\mo7\dy9\hr15\min18}{\printim\yr1996\mo7\dy9\hr15\min15}{\version4}{\edmins16}{\nofpages0}{\nofwords0}{\nofchars0}{\vern49203}}\widowctrl\ftnbj\aenddoc\formshade \fet0\sectd \linex0 {\*\pnseclvl1

\pnucrm\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl4\pnlcltr\pnstart1\pnindent720\pnhang{\pntxta )}}{\*\pnseclvl5

\pndec\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl8\pnlcltr\pnstart1\pnindent720\pnhang

{\pntxtb (}{\pntxta )}}{\*\pnseclvl9\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs24 Summary of Responses to Survey Question}{\i0\fs20

\par }\pard\plain \f4\fs20

\par \pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs20 Original question

\par }\pard\plain \f4\fs20 {\f9 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? \line \line (What are the major stumbling bloc

ks to clear writing that you've observed with yourself, your colleagues, or your students?)\line

\par }\pard\plain \s2\fi-180\li180 \b\i\f9\fs14 {\b0\i0\fs20 For context, what is your role in tech writing? \line

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\b0\i0\fs20 Any comments?\line }{\b0\fs20 ---------------------------------------------------------------------------------------------------------------------------

\par }\pard \s1\tqr\tx11880 {\fs20 Number of answers by category

\par }\pard\plain \s2\fi-360\li360\tqr\tx4500 \b\i\f9\fs14 {\b0\i0\fs20 *\tab Analyze audience & writing requirements\tab 12

\par }\pard \s2\fi-360\li360\tqr\tx4500 {\b0\i0\fs20 *\tab Write clearly\tab 23

\par *\tab Organize your material\tab 12

\par *\tab Visual considerations\tab 7

\par \tab Build the writer-editor partnership\tab 3

\par \tab Other\tab 6

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\b0\fs20 ---------------------------------------------------------------------------------------------------------------------------

\par }\pard \s1\tqr\tx11880 {\fs20 Analyze audience & writing requirements

\par }\pard\plain \s2\fi-360\li360 \b\i\f9\fs14 {\b0\i0\fs20 1.\tab If writer is very familiar with subject, beware not to overlook what audience needs

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 2.\tab Anticipate users\rquote problems and provide solutions rather than descriptions (define what the user needs)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 3.\tab Define

\par 4.\tab Define who, and what critical information they need

\par 5.\tab Don\rquote t describe what the software does, tell the reader how to use it

\par 6.\tab Forget all of your assumptions

\par 7.\tab Identify and write to their level

\par 8.\tab Know who they are and write to their level

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 9.\tab Tell them what they need to know (\ldblquote \'85don\rquote 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)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 10.\tab Write to your audience

\par 11.\tab Define the purpose for the documentation (how-to, reference, introduction, etc.)

\par 12.\tab Define the purpose of the document: understand it and stick to it

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs20

\par }\pard \s1\tqr\tx11880 {\fs20 Write clearly

\par }\pard\plain \s2\fi-360\li360 \b\i\f9\fs14 {\b0\i0\fs20 1. \tab Ask for help in clarification

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 2. \tab Avoid jargon

\par 3. \tab Keep writing simple: fewer words make reading easier

\par 4. \tab KISS

\par 5. \tab KISS

\par 6. \tab KISS principle

\par 7. \tab Repeat information rather than provide cross-references

\par 8. \tab Sentences: Avoid run-on sentences

\par 9. \tab Sentences: Avoid run-ons

\par 10. \tab Sentences: Keep them short

\par 11. \tab Sentences: Subject and verb agreement

\par 12. \tab Sentences: Use tense correctly

\par 13.\tab Sentences: Write short, single-topic sentences; avoid run-on sentences

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 14.\tab Sentences: (Discuss examples before & after rewrites; emphasize right & wrong way to arrange; how to begin & end)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 15.\tab The importance of clear writing: why technical editing is not just \ldblquote making it look pretty\rdblquote

\par 16.\tab Use grammar correctly

\par 17.\tab Voice: Correct use of active & passive

\par 18.\tab Voice: Eliminate passive constructions

\par 19.\tab Voice: Use active and passive voices correctly

\par 20.\tab Voice: Use active voice

\par 21.\tab Write clearly

\par 22.\tab Use standards

\par \tab a)\tab Agree on them; comply with specifications

\par \tab b)\tab Style guide; define nomenclature at the start of your project and keep it consistent

\par \tab c)\tab Style guides, especially in-house, including templates, application tools, who to call

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 \tab d)\tab Terminology: use terms consistently (example: Don\rquote t call something a \ldblquote user \tab interface\rdblquote in one paragraph and \ldblquote GUI\rdblquote in another.)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 \tab e)\tab Use change control procedures

\par }\pard \s2\fi-180\li180 {\b0\i0\fs20 23. Make your writing more readable

\par }\pard \s2\fi-180\li360 {\b0\i0\fs20 \tab a)\tab Acronyms & abbreviations: try not to use them. If you must use them, \line \tab define them.

\par }\pard \s2\fi-180\li360 {\b0\i0\fs20 \tab b)\tab Acronyms: follow rules (spell out on first appearance, repeat each \line \tab chapter, except common ones)

\par }\pard \s2\fi-180\li360 {\b0\i0\fs20 \tab c)\tab Acronyms: spell out the first time they\rquote re used in each chapter

\par \tab d)\tab Mechanics: Avoid comma splices

\par }\pard \s2\fi-180\li360 {\b0\i0\fs20 \tab e)\tab Mechanics: Don\rquote t use initial capitals on every word. Learn how to \line \tab determine whether something is really a proper noun

\par }\pard \s2\fi-180\li360 {\b0\i0\fs20 \tab f) \tab Mechanics: Hyphenate compound adjectives

\par \tab g)\tab Mechanics: Run your spell-checker

\par \tab h)\tab Agree on them; comply with specifications

\par }\pard \s2\fi-180\li180 {\fs20

\par }\pard \s2\fi-180\li180 {\fs20 Organize your material

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 1.\tab Organization

\par 2.\tab Organization: Identify task order

\par 3.\tab Organization: Organize your document logically

\par 4.\tab Organize information: Chunk, use organizing schemes

\par 5. \tab Index: Make it useful

\par 6. \tab Index: Provide multiple ways to find information

\par 7. \tab Index: Spend quality time on it

\par 8. \tab Make information easy to find

\par 9. \tab Provide a useful table of contents

\par 10. \tab Provide glossary

\par 11.\tab Provide glossary if necessary

\par 12. \tab Test for usability

\par }\pard\plain \f4\fs20 {\f9

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs20 Visual considerations

\par }\pard\plain \s2\fi-360\li360 \b\i\f9\fs14 {\b0\i0\fs20 1.\tab Format: Keep conventions consistent (house style guide helps here!)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 2.\tab Format & style: define best (easiest accessibility)

\par 3.\tab Graphics: Remember that a picture is worth 1000 words (figures, tables, pictures, etc.)

\par 4.\tab Graphics: Use lots of pictures and explain them

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 5.\tab Use bullets & numbered steps

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 6.\tab Use tables, figures, illustrations, diagrams, flowcharts, etc.

\par 7.\tab Write useful headings

\par }\pard \s2\fi-180\li180 {\fs20

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs20 Build the writer-editor partnership

\par }\pard\plain \s2\fi-360\li360 \b\i\f9\fs14 {\b0\i0\fs20 1.\tab Fortify writer-editor relationship

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 2.\tab Don\rquote t sweat the redlines! Technical writer or editor is not impugning your intelligence when correcting your grammar\emdash

this is especially important for those who learned English as a second language.

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 3.\tab Seek feedback and incorporate it.

\par 3.\tab Confidence in writing comes from understanding language basics.

\par }\pard \s2\fi-180\li180 {\fs20

\par }\pard\plain \s1\tqr\tx11880 \b\i\f9\fs16 {\fs20 Other

\par }\pard\plain \s2\fi-360\li360 \b\i\f9\fs14 {\b0\i0\fs20 1.\tab Language: Use gender-neutral language

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 2.\tab Accuracy: Proofread & review

\par 3.\tab Accuracy: Test for functional accuracy

\par 4.\tab Practice paragraph rewrites (discuss examples before & after rewrites)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 5.\tab Prepare to write (importance of reading good writing; keep notebook & take notes in meetings; get early start on your project)

\par }\pard \s2\fi-360\li360 {\b0\i0\fs20 6.\tab Prepare to write: Don\rquote t put off your projects until the last moment.

\par \tab \tab Assume your first draft will be awful!

\par \tab \tab This will allow time for REWRITING.

\par \tab \tab There are no finished projects only deadlines.

\par }\pard\plain \f4\fs20 {\f9

\par }}


Previous by Author: Re: QUERY: Long vs. Short Manuals
Next by Author: Summary TW Course (Resend)
Previous by Thread: WordPlay
Next by Thread: Indexing in WebSTAR


What this post helpful? Share it with friends and colleagues:


Sponsored Ads