Technical Writing

TechnicalWriting “Technical writingconveys specific information about a technical subject to a specific audience for a specific purpose.”

Bugs in Writing, Lyn Depre www.stc.org: Society for Technical Communication www.technical-writing-course.com: A short course on technical writing www.micron.com/k12/writing: Micron Writing in the Workplace www.critical-reading.com/inference_denotation.htm: Headlines Sources/Resources

Technical vs Creative Writing

The Challenge • Too often technical writing has a flat style making documents difficult and tedious to read. • There's no reason why technical writing shouldn't be lively and interesting. • The real challenge is to express complex ideas simply.

Characteristics of Effective Technical Writing • Clear—is easily understood by the intended audience without ambiguities. • Accurate—is factual, correct, free from bias. • Correct—follows both grammatical and technical conventions. • Comprehensive—contains all necessary information. • Concise—is clear and complete without excess or redundant verbiage. • Accessible—includes headings and subheads, indexes, and table of contents.

Tip 1: Identify your goals • Understand the type of technical report you are writing. • For example, the following demand different approaches: concept proposal, requirements specification, user guide • Write down your specific aim • Ask yourself ‘why am I writing’ and ‘what am I trying to achieve?’

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

With technical writing you must present your information so readers can: • extract the main points without necessarily reading the whole • easily find information that interests them • quickly absorb crucial information Therefore …

Tip 3: Structure well • Make use of headings and sub-headings, with a consistent numbering scheme. • Do not refer to information by reference number alone. • Itemize facts wherever possible. • Use textual highlighting for emphasis (italics, underlining, boldface).

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

For example You should structure your document well: • Make use of headings and sub-headings, with a consistent numbering scheme. • Do not refer to information by reference number alone. • Itemize facts wherever possible. • Use textual highlighting for emphasis (italics, underlining, boldface).

Tip 4: Clarify and Illustrate • Use examples (scenarios) • Use illustrations, diagrams • Use flowcharts, graphs, tables ---------------------------------------------------------- • If a description is complex, repeat it using a different approach

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

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

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

Tip 5: KISS Use simple words rather than complex ones ----------------------------------------------------------- As we noted in the preceding section, if youpurchasedadditionalprinter options, such as a second printer tray, it is a requirement you verify its correct installation. ----------------------------------------------------------- As we noted in the previous section, if you boughtextra printer equipment, such as a second printer tray, you mustcheck that you installed it correctly.

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

You show the agent actively Passive: When memory is so short that it cannot be freed sufficiently fast to satisfy demand, swapping can be used. Active: When the operating system becomes so short of memory that the paging process cannot free memory sufficiently fast to satisfy demand, it can use swapping.

Tip 7: Avoid Ambiguity Actual Headlines: • Drunk Gets Nine Months in Violin Case • Kids Make Nutritious Snacks • New Vaccine May Contain Rabies • New Study of Obesity Looks for Larger Test Group • Police Begin Campaign to Run Down Jaywalkers • Red Tape Holds Up New Bridge • Local High School Dropouts Cut in Half

Summation • Identify your goals • Know your audience • Structure well • Clarify and illustrate • KISS • Use Active voice • Avoid ambiguity

Writing tips specific to Requirements • Not Design • Atomic • Verifiable • Achievable More examples …

` All error messages must be helpful ----------------------------------------------------------- Every registered user must have a unique UserID that will be used as a key field in a database table. ----------------------------------------------------------- The control total is taken from the last record. -----------------------------------------------------------

Req 5.2.3: The Word Search puzzle area must be rectangular in shape and no more than 60 characters wide. ----------------------------------------------------------- The output should usually be presented on the screen within 10 seconds of the user pressing the Enter Key. ----------------------------------------------------------- Using the set of words, the system will generate a crossword puzzle within 2 seconds. -----------------------------------------------------------

When an error message is generated about the sales data, it should be dumped to the audit file. ---------------------------------------------------------- If the user is experience level 2, or has root access, then accept the amount provided as input and print the accepted message; otherwise, if the experience level is 1, then print message 1.

Citation of Sources How? There are many styles, all easily accessible. When? See our graduate Independent Study page: www.csc.villanova.edu:8080/academics/gradIS 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 aspiringconcurrent 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.

Technical Writing