英语重点技术写作

Guidelines to Successful Technical Writing1. Revising with efficient sentencesThe main purpose of a technical document is to inform or persuade the reader through use of efficient sentences, not to impress or entertain with fancy language displays. So, technical documents transmit worthwhile informationeven highly specialized informationin the most straightforward way to their audience.Readers of technical documents are busy and impatient. They do not wish to put more into reading a document than they can get from it. They hate waste and expect efficiency. Every sentence in a document should be revised to carry its own weight, in conveying the writers meaning.Observe the same rule in adopting sentence style as you would in choosing the documents content: make it long enough to be understood, yet short enough to be tolerated. When writing a technical document, consult the guidelines below, which can also serve as a checklist for your sentence style:q Revise sentences to be clear and avoid ambiguity.A clear sentence communicates its precise meaning on first reading. It signals relationships among its parts, and emphasizes the key thought. In technical writing, a sentence should have only one meaning. Make sure the words, phrases, and punctuation are absolutely clear.Ambiguous I cannot recommend this candidate too highly.Revised This candidate has my highest recommendation. Ambiguous Many executives are skeptical about office automation as well as managers.Revised Many executives as well as managers are skeptical about office automation.Ambiguous Being well-known in the computer industry, our project would benefit a lot from the Tsinghua team.Revised Because the Tsinghua team is well-known in the computer industry, our project would benefit a lot from its help.q Use active rather than passive voice most of the time.Usually, the active voice (Joe tested the software.) is better than the passive voice (The software is tested by Joe.), but in certain situations it can make sense to use the less natural passive style. However, many writers routinely use the passive style simply because they believe it is more “formal” and “acceptable”. It is not. Using the passive style is the most common reason for poorly structured sentences and it always leads to longer sentences than are necessary. Unless you have a very good reason for the change in emphasis, you should always write in the active style.The following examples show the improvement achieved by switching from passive to active:FaultyThe report was written by Peter, and was found to be excellent.Correct Peter wrote the report, and it was excellent.FaultyThe lid should be sealed with wax.Correct Seal the lid with wax.BadThe values were measured automatically by the control system.GoodThe control system measured the values automatically.Weak & Impersonal An offer will be made by us next week.StrongerWe will make you an offer next week.q Avoid unnecessary words and repetition.Many sentences contain unnecessary words that repeat an idea already expressed in another word. This wastes space and blunts the message. Often writers use several words for ideas that can be expressed in one. This leads to unnecessarily complex sentences and redundancy.RedundantThe printer is located adjacent to the computer. Revised The printer is adjacent to the computer.RedundantThe user can visibly see the image moving.RevisedThe user can see the image moving.Redundant The product is not of a satisfactory nature.Revised The product is unsatisfactory.q Make sentences fluent.Fluent sentences are polished, graceful, and easy to read. Varied length and word order make them free of choppiness and monotony. See the following suggestions:Needless “that” This is a problem that bothers me.Fluent This problem bothers me.Needless qualifier It seems that they have a valid argument.Revised They have a valid argument. / They seem to have a valid argument.Choppy Jogging can be healthful if you have the right equipment. Most important are well-fitting shoes. They are important because without them you take the chance of injuring your legs. Your knees are especially prone to injury.Revised Jogging can be healthful if you have the right equipment. Well-fitting shoes are most important because they prevent injuries to your legs, especially your knees.Technical writing exercises 1. The following sentences are unclear or lack fluency because of ambiguous phrasing, incorrect word order, or too much information. Revise them so that their meanings are clear.a) A man eating shark was spotted in the South Sea.b) Wearing special equipment, the radioactive material failed to injure the operator.c) That is a whole new approach that needs attention and research.2. The following sentences need to be rewritten in the active or passive voice for better emphasis, more directness or greater economy. Make necessary changes and give reasons for each.a) It is believed by us that the contract is faulty.b) Special helmets should be worn at all times during this project.c) It was reported by the manager that the project was in trouble.d) Care should be taken in the operation of the machine.Guidelines to Successful Technical Writing2. Choosing the right words and expressionsYour choice of words ultimately determines the quality of your writing. Keep your expression simple, jargon-free, original, convincing, precise, concrete and specific.q Replace difficult words and phrases with simpler alternatives.Flowery diction and needless jargon obscure your message and force your readers to work too hard for understanding. Word it in plain English, and avoid inflated diction. Do not use three syllables when one will do. Here is a list of a number of words and expressions that should generally be avoided in favor of the simple alternative.approximately=aboutascertain=findassist, assistance=helpcommence=startdemonstrate=showdwelling=houseeffectuate=do(to) endeavor=(to) tryendeavor=effortenquire=askfacilitate=helpin consequence=soin excess of=morein respect of=aboutin the event of=ifinitiate-beginmultiplicity of=manynecessitate-needphenomenon=eventterminate=end, stoptransmit=sendutilize=useOwing to the situation that. = Because, sinceShould a situation arise where. = IfTaking into consideration such factors as. = ConsideringAlso, unless you are discussing building maintenance or computer graphics, never use the verb “render”.Faulty The testing strategy rendered it impossible to find all the faults.Correct The testing strategy made it impossible to find all the faults.In other words, if you mean “make” then write “make” not “render”.Count the syllables and trim when you can. The following is an example of bad diction inflation:Inflated Re-evaluate the design of the entire user interface to minimize design factors which are resulting in sensitive and/or critical maintenance and inspection procedures.Revised Redesign the UI so they are easier to maintain and inspect.q Use verbs instead of nouns if possible.Look at the following sentence:Half the team was involved in the development of system Y.This sentence contains a classic example of a common cause of poor writing style. The sentence is using the abstract noun “development” in place of the verb “develop”. The simpler and more natural version of the sentence is:Half the team was involved in developing system Y.Turning verbs into abstract nouns always produces sentences longer than necessary, so avoid doing it. The following examples show the improvement you can achieve by replacing nouns with verbs:Faulty He used to help in the specification of new software.Revised He used to help specify new software.Faulty Clicking the icon causes the execution of the program.Revised The program executes when the icon is clicked.Faulty The analysis of the software was performed by Fred.Revised Fred analyzed the software.Faulty It was reported by Jones that method Z facilitated the utilization of inspection techniques by the testing team.Revised Jones reported that method Z helped the testing team use inspection techniques.q Use jargon only if it helps you communicate better.Expressions like MS/DOS, UI, ODBC and glitch are examples of jargon. In general, jargon refers to a special vocabulary of a particular group or activity. It is often shorthand or abbreviations, with specialized usage. If you are confident that every reader of your report understands the specialty, then it may be used. For example, if your only potential readers are computer specialists, it is appropriate to say that a computer is down without having to explain what “down” means. In all other cases (which are almost always) jargon should be avoided. If you cannot avoid using such expressions, then define the term the first time you use it or refer the reader to a glossary where it is defined.Needless jargonIntercom utilization will be used to initiate overtime programmeroperative involvement.RevisedProgrammers who have to work overtime will be notified on theintercom.q Be consistent in naming the same subject or object.The rule “Never use the same word twice.” does not apply to all forms of writing. Some people may feel they must use different words to describe the same thing. In technical writing the opposite rule applies: “You should always use the same word to refer to the same thing.” Failing to do so may confuse and annoy readers.Consider, for example, the following paragraph that was written in a group project final report:In the first three weeks of the project we wrote a project plan for the system.We were ambitious in our requirements because we wanted the group project to be a success and we wanted the software to be of high quality. In fact, we were determined that our software would be very satisfactory. By die end we realized there were major problems with the project. The first increment of the project we delivered was inconsistent with the requirements specification and it was clear the final code would not be the best system as there were clearly better groups than ours.The problem with this paragraph is that there are three key objects that are referred to in different and inconsistent ways. The objects are:The project: It refers to the entirety of the group experience.The plan: It refers to a document describing the requirements and the schedule for implementing them.The system: It refers to the software system that the group project is supposed to deliver.*3*1ijit.4JUnfortunately, we find that these things are referred to in different parts of the paragraph as:The project: project; group project; group.The plan: project plan; requirements; requirements specification. The system: system; software; project; code; final code.In situations such as this, it is important to identify each different object first and decide once and for all how it should be named. Once you have made this decision consistently use the same name throughout when you refer to that object. Applying this instruction to the example above will yield the following improved text:In the first three weeks of the project we wrote a plan for the system. Our plan was ambitious because we wanted the project to be a success and we wanted the system to be high quality. In fact, we were determined that our project would be very satisfactory. By the end we realized there were major problems with the project. The first increment of the system we delivered was inconsistent with the plan and it was clear the final system would not be the best system as there were clearly better projects than ours. Technical writing exercises 1. Improve the economy and directness of the following sentences by replacing difficult words and phrases with simpler alternatives, and replacing nouns with verbs.a) Do not hesitate to contact us in the event that you are in need of assistance for the computer software application at any time.b) Bill made the suggestion that we hire an additional systems analyst.c) We request the formation of a committee of experienced software engineers for the review of quality discrepancies.2. Revise the following paragraph to make it more internally consistent and readable.Good software engineering is based on a number of key principles. One such principle is for the group to get a good understanding of the customer requirements. It is also important to deliver in regular increments, involving the client as much as possible. Another rule is that it is necessary to do unit testing, black box and white box testing throughout, with unit testing being especially crucial. In addition to the previous doctrines, a programmer needs to be able to maintain good communication within the software team (and also with the user).Guidelines to Successful Technical Writing3. Grammar, punctuation & mechanicsUnits 1 and 2 explained the most important principles for improving the style of your writing. However, it is also important (and actually easier) to improve the grammar, punctuation and mechanics of your writing. No matter how vital and informative a message may be. its credibility is damaged if it contains errors. Any errorsillogical, fragmented, or run-on sentences; faulty punctuation: poorly chosen wordsstand out and mar otherwise good writing.This section provides several guidelines to avoid the most commonly made language errors. Although it offers no easy solution to long-standing fundamental problems in writing, it does provide a simple guide for basic improvement. You may discover that some writing problems are easier to solve than you had realized.Grammarq Be aware of dangling modifiers.A dangling modifier, a common case of English misusage. is a verbal phrase, prepositional phrase, or dependent clause that does not refer to the subject in its sentence. Correct it by rewriting the sentence to make the modifier correspond with the subject.DanglingAfter a night of hard work, the bug was finally fixed.RevisedAfter we had worked all night, the bug was finally fixed.Dangling Without knowing the final design, it is difficult to make plans for the implementation.Revised Because we have not received the final design, it is difficult to make plans for the implementation.Dangling The project ended up a failure, not having studied the user requirements carefully.Revised We could not complete the project, not having studied the user requirements carefully.q Avoid run-on sentences.Run-on sentences cram too many ideas into one sentence without providing needed breaks or pauses between thoughts.Run-on The hourglass is more accurate than the water clock for the water in a water clock must always be of the same temperature in order to flow with the same speed since water evaporates it must be replenished at regular intervals thus not being as effective in measuring time as the hourglass.Revised The hourglass is more accurate than the water clock because water in a water clock must always be of the same temperature to flow at the same speed. Also, water evaporates and must be replenished at regular intervals. These temperature and volume problems make the water clock less effective than the hourglass in measuring time. q Avoid faulty subject and verb agreement. Failure to make the subject of a sentence agree in person and number with the verb is a common writing error. Luckily, it is an error easily avoided or corrected. In short sentences, where the subject and the verb are not far apart, this mistake is not likely to occur; however, in more complicated sentences, you may lose track of the subject-verb relationship.Faulty Everyone in the development group and the testing group have worked long hours.Correct Everyone in the development group and the testing group has worked long hours. Faulty The high number of software projects that failed this year are disappointingCorrect The high number of software projects that failed this year is disappointing.Faulty Computer security techniques and a workable plan for evading various kinds of hacker attacks requires large expenditures.Correct Computer security techniques and a workable plan for evading various kinds of hacker attacks require large expenditures.q Avoid sentence shifts.Shifts in point of view damage coherence. If you begin a sentence or paragraph with one subject or person, remain with it.Shift in person When you have managed to write professional English technical documents, one will have a great sense of achievement.Revised When you have managed to write professional English technical documents, you will have a great sense of achievement.Shift in voice He delivered the specs for system design, and the UML diagrams were also revised by him.Revised He delivered the specs for system design, and also revised the UML diagrams.Shift in number One should send the project manager a progress report before theyare off work.Revised One should send the project manager a progress report before one isoff work.OrSend the project manager a progress report before getting off work.Punctuationq Use semicolons with adverbs as conjunctions.You must use semicolons, not commas, to accompany adverbs and other expressions that connect related independent ideas. Here are some common adverbs: besides, otherwise, still, however, furthermore, moreover, consequently, therefore, on the other hand, in contrast, in fact. For example:The project was finally completed; however, the customers were not very satisfied.Designing such a complicated system is too demanding; in fact, no one is sure if we can make it within the time limit.q Use colons only after an independent clause.The colon introduces explanations or lists.She is an ideal colleague: honest, reliable, and competent.Do not place a colon directly after a verb.FaultyOur plans include: analyzing the requirements, hiring two newprogrammers, getting enough funds, and getting the work done.q Use hyphens to avoid ambiguity.re-creation (a new creation) recreation (leisure activity)Mechanicsq Consider your audience before using abbreviations.Do not use abbreviations that might confuse your reader. Often, abbreviations are not appropriate in formal writing. When in doubt, write out the full words.Correct Check component No. 3.Faulty Mr. Zhang, our specialist consultant, is a Dr.q Always avoid abbreviating words out of laziness. For example: never write approx. for approximately (it may be better to write about); never write e.g. for for example.Technical writing exercises 1.Locate an English technical document. Study the document and ask yourself if it conforms to the principles discussed in the guide above. If not, how could you improve its grammar, punctuation, and mechanics? Discuss your conclusion in class or write it in one or two paragraphs.2.The following sentences need to be revised. Make necessary changes and be prepared to give reasons for each.a) Reforming a design specification is beyond our means, we have no time left for that.b) Ja