TechnicalTechnical WritingWriting

““Technical writingTechnical writing conveys specific conveys specific information about a technical subject to information about a technical subject to

a specific audience for a specific a specific audience for a specific purpose.”purpose.”

Sources/ResourcesSources/Resources

Bugs in Writing, Lyn DepreBugs in Writing, Lyn Depre

www.stc.org: Society for Technical www.stc.org: Society for Technical CommunicationCommunication

www.technical-writing-course.com:www.technical-writing-course.com:

A short course on technical writingA short course on technical writing

www.micron.com/k12/writing: Micron Writing in www.micron.com/k12/writing: Micron Writing in the Workplacethe Workplace

www.critical-reading.com/www.critical-reading.com/inference_denotation.htm: Headlinesinference_denotation.htm: Headlines

Technical vs Creative WritingTechnical vs Creative Writing

TechnicalTechnical CreativeCreative

ContentContent factual, straight-factual, straight-forwardforward

imaginative, symbolicimaginative, symbolic

AudienceAudience specificspecific generalgeneral

PurposePurpose inform, instructinform, instruct entertain, provoke, entertain, provoke, inspireinspire

StyleStyle formal, standardformal, standard informal, artisticinformal, artistic

ToneTone objectiveobjective subjectivesubjective

VocabularyVocabulary specializedspecialized general, evocativegeneral, evocative

OrganizationOrganization sequential, systematicsequential, systematic arbitrary, artisticarbitrary, artistic

The ChallengeThe Challenge

Too often technical writing has a flat style Too often technical writing has a flat style making documents difficult and tedious to making documents difficult and tedious to read. read.

There's no reason why technical writing There's no reason why technical writing shouldn't be lively and interesting. shouldn't be lively and interesting.

The real challenge is to express complex The real challenge is to express complex ideas simply. ideas simply.

Characteristics of Characteristics of Effective Technical WritingEffective Technical Writing

ClearClear—is easily understood by the intended audience —is easily understood by the intended audience without ambiguities.without ambiguities.

AccurateAccurate—is factual, correct, free from bias.—is factual, correct, free from bias.

CorrectCorrect—follows both grammatical and technical —follows both grammatical and technical conventions.conventions.

ComprehensiveComprehensive—contains all necessary information.—contains all necessary information.

ConciseConcise—is clear and complete without excess or —is clear and complete without excess or redundant verbiage.redundant verbiage.

Accessible—Accessible—includes headings and subheads, indexes, includes headings and subheads, indexes, and table of contents.and table of contents.

Tip 1: Identify your goalsTip 1: Identify your goals

Understand the type of technical report Understand the type of technical report you are writing.you are writing. For example, the following demand different For example, the following demand different

approaches: concept proposal, requirements approaches: concept proposal, requirements specification, user guidespecification, user guide

Write down your specific aimWrite down your specific aim Ask yourself ‘why am I writing’ and ‘what am I Ask yourself ‘why am I writing’ and ‘what am I

trying to achieve?’trying to achieve?’

Tip 2: Know your audienceTip 2: Know your audience

Match your content to your readers’ Match your content to your readers’ knowledge. knowledge. If you are in doubt, aim for the simpler If you are in doubt, aim for the simpler approach.approach.If appropriate, include several alternate If appropriate, include several alternate levels of info.levels of info.Define your terms.Define your terms. computer terminology fluidcomputer terminology fluid if many terms need definition, use a glossaryif many terms need definition, use a glossary

With technical writing you must present your With technical writing you must present your information so readers can: information so readers can:

extract the main points without necessarily extract the main points without necessarily reading the wholereading the whole

easily find information that interests themeasily find information that interests them

quickly absorb crucial informationquickly absorb crucial information

Therefore …Therefore …

Tip 3: Structure wellTip 3: Structure well

Make use of headings and sub-headings, Make use of headings and sub-headings, with a consistent numbering scheme.with a consistent numbering scheme.

Do not refer to information by reference Do not refer to information by reference number alone.number alone.

Itemize facts wherever possible.Itemize facts wherever possible.

Use textual highlighting for emphasis Use textual highlighting for emphasis (italics, underlining, boldface).(italics, underlining, boldface).

For exampleFor example

It is important to structure your document It is important to structure your document well. You should make use of headings and well. You should make use of headings and sub-headings, with a consistent numbering sub-headings, with a consistent numbering scheme. Remember not to refer to scheme. Remember not to refer to information by reference number alone. information by reference number alone. Additionally it is important to itemize facts Additionally it is important to itemize facts wherever possible. Finally, you can wherever possible. Finally, you can sometimes use textual highlighting for sometimes use textual highlighting for emphasis (italics, underlining, boldface).emphasis (italics, underlining, boldface).

For exampleFor example

You should structure your document well:You should structure your document well:

Make use of headings and sub-headingsMake use of headings and sub-headings, , with a consistent numbering scheme.with a consistent numbering scheme.

Do not refer to information by reference Do not refer to information by reference number alonenumber alone..

Itemize factsItemize facts wherever possible. wherever possible.

Use textual highlightingUse textual highlighting for emphasis for emphasis (italics, underlining, boldface).(italics, underlining, boldface).

Tip 4: Clarify and IllustrateTip 4: Clarify and Illustrate

Use examples (scenarios)Use examples (scenarios)

Use illustrations, diagramsUse illustrations, diagrams

Use flowcharts, graphs, tablesUse flowcharts, graphs, tables

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

If a description is complex, repeat it using If a description is complex, repeat it using a different approacha different approach

Tip 5: KISS (short and simple)Tip 5: KISS (short and simple)

Avoid long sentences that present several facts.Avoid long sentences that present several facts. ----------------------------------------------------------------------------------------------------------------------If the sales for the current month are below the If the sales for the current month are below the target sales, then a report is to be printed, unless target sales, then a report is to be printed, unless the difference between the target sales and actual the difference between the target sales and actual sales is less than half of the difference between sales is less than half of the difference between target sales and actual sales in the previous target sales and actual sales in the previous month, or if the difference between target sales month, or if the difference between target sales and actual sales for the current month is under and actual sales for the current month is under 5%.5%.

CompareCompare(One Sentence—70 words)(One Sentence—70 words) A highlight of the web site is the development of two types A highlight of the web site is the development of two types of electronic advisory systems—Expert and Technical of electronic advisory systems—Expert and Technical where both of the systems inform the user about standards where both of the systems inform the user about standards by either asking a series of questions which determine by either asking a series of questions which determine whether, how, and which specific parts of the standard whether, how, and which specific parts of the standard apply to the user's activities, or addressing complex apply to the user's activities, or addressing complex standards by placing in one location a large amount of standards by placing in one location a large amount of information about the standard. information about the standard. ------------------------------------------------------------------------------------------------------------------------------------(Three sentences—Total 42 words)(Three sentences—Total 42 words)The web site offers both expert and technical advice The web site offers both expert and technical advice sections. These explain standards by asking questions to sections. These explain standards by asking questions to find out if and how the standards apply to the user. They find out if and how the standards apply to the user. They also address complex standards by placing all the relevant also address complex standards by placing all the relevant information in one place. information in one place.

Tip 5: KISSTip 5: KISS

Omit needless words and informationOmit needless words and information--------------------------------------------------------------------------------------------------------------------It is very important that every single generated error message, no It is very important that every single generated error message, no matter how minor of an error, be carefully recorded by the Foobar matter how minor of an error, be carefully recorded by the Foobar system in the audit file for future consideration by the maintenance system in the audit file for future consideration by the maintenance engineers who will try to improve the system’s reliability.engineers who will try to improve the system’s reliability.

It is very important that It is very important that everyevery single single generated error messagegenerated error message, no , no matter how minor of an error, be carefully matter how minor of an error, be carefully recordedrecorded by the by the FoobarFoobar system system in the audit filein the audit file for future consideration by the maintenance for future consideration by the maintenance engineers who will try to improve the system’s reliability.engineers who will try to improve the system’s reliability.

--------------------------------------------------------------------------------------------------------------------Foobar must record every generated error message in the audit file.Foobar must record every generated error message in the audit file.

Tip 5: KISSTip 5: KISS

Use simple words rather than complex onesUse simple words rather than complex ones----------------------------------------------------------------------------------------------------------------------As we noted in the As we noted in the precedingpreceding section, if you section, if you purchasedpurchased additionaladditional printer printer optionsoptions, such as a , such as a second printer tray, it is a second printer tray, it is a requirementrequirement you you verifyverify its correct installation.its correct installation.----------------------------------------------------------------------------------------------------------------------As we noted in the As we noted in the previousprevious section, if you section, if you boughtbought extraextra printer printer equipmentequipment, such as a second printer , such as a second printer tray, you tray, you mustmust checkcheck that you installed it correctly. that you installed it correctly.

Tip 6: Use Active VoiceTip 6: Use Active VoicePassive verbs are longwinded, ambiguous and dull. Active Passive verbs are longwinded, ambiguous and dull. Active verbs make your writing simpler, less awkward, clearer and verbs make your writing simpler, less awkward, clearer and more precise. more precise. --------------------------------------------------------------------------------------------------------------------The QMS Magicolor 2 PrinterThe QMS Magicolor 2 Printer is equipped is equipped with two with two interfaces, one interfaces, one is knownis known as the parallel interface, the other as the parallel interface, the other is knownis known as the Ethernet interface. Whatever interface as the Ethernet interface. Whatever interface connectionconnection is needed is needed, you will find that MS Windows 98 , you will find that MS Windows 98 has already has already been preinstalledbeen preinstalled and your software and your software applications applications are basedare based on this platform. on this platform. ----------------------------------------------------------------------------------------------------------------------The QMS Magicolor 2 Printer has Parallel and Ethernet The QMS Magicolor 2 Printer has Parallel and Ethernet interfaces. Whatever interface you need, you will find your interfaces. Whatever interface you need, you will find your software applications will work on the preinstalled MS software applications will work on the preinstalled MS Windows 98. Windows 98.

You show the agent activelyYou show the agent actively

Passive: When memory is so short that it Passive: When memory is so short that it cannot be freed sufficiently fast to satisfy cannot be freed sufficiently fast to satisfy demand, swapping can be used.demand, swapping can be used.

Active: When the Active: When the operating systemoperating system becomes becomes so short of memory that the so short of memory that the paging processpaging process cannot free memory sufficiently fast to cannot free memory sufficiently fast to satisfy demand, satisfy demand, itit can use swapping. can use swapping.

Tip 7: Avoid AmbiguityTip 7: Avoid Ambiguity

Actual Headlines:Actual Headlines:Drunk Gets Nine Months in Violin CaseDrunk Gets Nine Months in Violin CaseKids Make Nutritious SnacksKids Make Nutritious SnacksNew Vaccine May Contain RabiesNew Vaccine May Contain RabiesNew Study of Obesity Looks for Larger Test New Study of Obesity Looks for Larger Test GroupGroupPolice Begin Campaign to Run Down Police Begin Campaign to Run Down JaywalkersJaywalkersRed Tape Holds Up New BridgeRed Tape Holds Up New BridgeLocal High School Dropouts Cut in HalfLocal High School Dropouts Cut in Half

SummationSummation

1.1. Identify your goalsIdentify your goals

2.2. Know your audienceKnow your audience

3.3. Structure wellStructure well

4.4. Clarify and illustrateClarify and illustrate

5.5. KISSKISS

6.6. Use Active voiceUse Active voice

7.7. Avoid ambiguityAvoid ambiguity

Writing tips specific to Writing tips specific to RequirementsRequirements

Not DesignNot Design

AtomicAtomic

VerifiableVerifiable

AchievableAchievable

More examples …More examples …

`̀All error messages must be helpfulAll error messages must be helpful

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

Every registered user must have a unique Every registered user must have a unique UserID that will be used as a key field in a UserID that will be used as a key field in a database table.database table.

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

The control total is taken from the last The control total is taken from the last record.record.

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

Req 5.2.3: The Word Search puzzle area must be Req 5.2.3: The Word Search puzzle area must be rectangular in shape and no more than 60 rectangular in shape and no more than 60 characters wide.characters wide.

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

The output should usually be presented on the The output should usually be presented on the screen within 10 seconds of the user pressing the screen within 10 seconds of the user pressing the Enter Key.Enter Key.

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

Using the set of words, the system will generate a Using the set of words, the system will generate a crossword puzzle within 2 seconds.crossword puzzle within 2 seconds.

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

When an error message is generated about When an error message is generated about the sales data, it should be dumped to the the sales data, it should be dumped to the audit file.audit file.

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

If the user is experience level 2, or has root If the user is experience level 2, or has root access, then accept the amount provided as access, then accept the amount provided as input and print the accepted message; input and print the accepted message; otherwise, if the experience level is 1, then otherwise, if the experience level is 1, then print message 1.print message 1.

Citation of SourcesCitation of Sources

How? There are many styles, all easily How? There are many styles, all easily accessible.accessible.

When?When?See our graduate Independent Study page:See our graduate Independent Study page:www.csc.villanova.edu:8080/academics/gradISwww.csc.villanova.edu:8080/academics/gradIS

Don’t plagiarize: Consider …Don’t plagiarize: Consider …

Plagiarism Example:

Suppose a journal article begins:

“A classic problem in concurrent programming is that of the ‘dining philosophers’ which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming; one in particular is Parlog86.”

You are to write a report about the article …

Blatant Plagiarism - Illegal:

Suppose a journal article begins:“A classic problem in concurrent programming is that of the ‘dining philosophers’ which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a classic problem in concurrent programming, the ‘dining philosophers’ problem, which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming, including Parlog86.

Even this is plagiarism:Suppose a journal article begins:“A classic problem in concurrent programming is that of the ‘dining philosophers’ which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a problem in concurrent programming, the ‘dining philosophers’ problem. Any aspiring concurrent program language is challenged by the power of this classic problem. In recent times, an increasing number of logic programming languages have been revised to handle concurrent programming, including Parlog86.

Here’s a legal approach, but its not very good:

Suppose a journal article begins:“A classic problem in concurrent programming is that of the ‘dining philosophers’ which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming; one in particular is Parlog86.”

The paper Parlog86 and the Dining Logicians revolves around a classic problem in concurrent programming, the ‘dining philosophers’ problem. The paper says the problem “challenges the power of any aspiring concurrent program language.” As noted in the same paper “recently, a growing number of logic programming languages have been refined to handle concurrent programming, including Parlog86.” [Ringwood 1988]

Best is to use your own words: Suppose a journal article begins:“A classic problem in concurrent programming is that of the ‘dining philosophers’ which challenges the power of any aspiring concurrent program language. Recently, a growing number of logic programming languages have been refined to handle concurrent programming; one in particular is Parlog86.”

In our Operating Systems class, we studied the “dining philosophers” problem. This problem uses philosophers and chop sticks to represent computer processes and resources, and models common resource contention problems. A good test of a concurrent programming language is to see how it does in solving this problem. That is what is done with Parlog86, a logic programming language, in the paper Parlog86 and the Dining Logicians.