Learning Enough English¶
Technical writing involves the creation of functional documents. Hence, the document needs to combine technical sophistication with clarity, conciseness, and a coherent manner of expression.
It becomes very important for a technical writer to explain the task in easy-to-understand and comprehensible language.
Which language do you think they should consider addressing their audience?
TW’s can get the answer after conducting proper audience analysis.
Globally, English is accepted as a mode of communication. The English read and write are of two types: UK and US. Aside from spelling and vocabulary, there are certain grammar differences between UK and US English which technical writer needs to make note of to avoid misinterpretation.
Therefore, it is very important to know English grammar with its rules to avoid errors and make it effective. (Errors are highly discouraged in technical writing!)
The ingredients which make our plate of expression understandable and easy to comprehend include the word you use to define, the sentence structure, the tone, the mood you choose to discuss the topic, grammatical perfection, and punctuations you set to express yourself.
It should be noted that the grammar is essential elements of the document for the relevance of the message. Similarly, style is essential element from the visual point of view. Style helps to provide visual cues and familiarity of the user with the product. For example, garland of flowers has all kinds of flowers in it, but which flower to use and the pattern for making the flowers makes all the difference.
Likewise, grammar is your element and style helps you decorate the content.
Basic Ingredients¶
Let us understand more about the various ingredients in detail:
Words¶
Words are the basic ingredient. TW should use words that are meaningful and easy to understand. In technical writing, TW is not supposed to show their vocabulary richness rather appropriate and comprehensible use of words. Choose words that are short and direct.
For example:
| Vocabulary | Replace with |
|---|---|
| Athenaeum | library |
| ken | knowledge |
| Concomitant | results |
| Assiduous | industrious |
Define new or unfamiliar terms¶
When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience.
Use terms consistently¶
Because of the richness of the English language, the words that you choose will probably have more than one meaning. However, you can reduce the confusion over which meaning a word has in a particular context by using the word consistently with only one of its meanings.
For example:
| Ambiguous | Clear |
|---|---|
| in spite of | regardless of, despite |
| may | can, might |
| on the other hand | however |
| since | because |
Use acronyms properly¶
On the initial use of an unfamiliar acronym within a document or a section, spell out the full term, and then put the acronym in parentheses. Put both the spelled-out version and the acronym in boldface.
For example:
Original - AWS offers reliable, scalable, and inexpensive cloud computing services.
Revision - Amazon Web Services(AWS) offers reliable, scalable, and inexpensive cloud computing services.
Avoid extraneous words¶
Avoid words that are not related to the context. Avoid phrasal verbs that might be confusing for non native English translators. Make every word count. Eliminate words that do not contribute to the meaning.
For example:
| Imprecise verbs | Precise verbs |
|---|---|
| have the capability to | can |
| make a distinction | distinguish |
| give rise to | cause |
| have knowledge of | know |
Proper choice of words¶
Avoid imprecise words, intensifiers and unnecessary modifiers. Try to eliminate words that do not contribute to the meaning.
Imprecise words that are not precise or exact; containing some error or uncertainty such as “now has plans to”, “makes use of”, “kinds of”.
Intensifying words adverbs or adverbial phrases that strengthen the meaning of other expressions and show emphasis such as “basically”, “significantly”, “very”, “specifically”, “really”, “some”, “any” .
A modifier is a word, phrase, or clause that modifies—that is, gives information about—another word in the same sentence such as “black box”, “black” is a modifier.
Check spelling of words¶
Make sure the spellings are correct throughout the document. A word that is spelled inconsistently or incorrectly might confuse users and translators.
For example:
‘’database’‘ and ‘’data base’‘
‘’email’‘, ‘’E-mail’‘, and ‘’e-mail’‘
‘’filename’‘ and ‘’file name’‘
‘’meta data’‘, ‘’metadata’‘, and ‘’meta-data’‘
Sentences¶
To convey the message, we use sentence structure for expression. Therefore, it becomes very important that we pay attention to the sentence structure and its meaning, it is conveying the message we intend it to.
Use crisp and short sentences¶
In technical writing, sentences used should be crisp, short and meaningful. The sentences used should not be repetitious in meaning. It is always better to express yourself in one sentence rather than conveying the same message in three long sentences.
Avoid negative sentences¶
Research shows that readers have more trouble understanding a sentence that has double negatives than an equivalent positive sentence. Replace the negative sentence with equivalent positive sentence.
For example:
Original sentence - Do not install software until you check that your computer does not have these conflicting programs.
Revised sentence - Before you install software, check that your computer does not have these conflicting programs
Follow parallelism¶
Balance the parts of sentence structure parallelly. Make explicit the logical flow from idea to idea. This flow can take many forms, such as from sentence to sentence, from paragraph to paragraph, from a paragraph to a list, table, figure, or example, and back again.
For example:
Original - Learn how using SQL Server manage your database needs, both on-premises and in the cloud.
Revision - Learn how to use SQL Server to manage your database needs, both on-premises and in the cloud.
Reduce there is/there are¶
Sentences that start with there is or there are marry a generic noun to a generic verb. Removing There is replaces the generic subject with a better subject.
Provide data instead of adverb/adjective¶
Limit the use of adjectives and adverbs in sentences. Try to provide data to be more compelling and credit your comparison instead of using adjectives/adverbs.
Choose strong verbs¶
Many technical writers believe that the verb is the most important part of a sentence. Choose strong verbs. Pick the right verb and the rest of the sentence will take care of itself.
Make clear syntax of sentences¶
Make the syntax of sentences clear by appropriately using conjunctions, articles, prepositions, and relative pronouns. Improve the passage in terms of abstract, general, and specific language.
Use short paragraphs¶
Try to form short paragraph which conveys the exact message you wanted to convey. Write paragraphs with great opening. Each paragraph should cover a single topic. Avoid long paragraphs, include only four to five sentences in a paragraph covering what, why and how.
Avoid cleft sentences¶
A cleft sentence opens with a special type of subject clause (an it-clause, a what-clause, or a similar clause) that changes the focus by adding two or three words (such as it, was, and who; there, are, and that; or what and was). In some contexts, a cleft sentence may imply a contrast or mistake. Therefore, avoid cleft sentences.
Original - It’s not that file will get saved in the directory.
Revision - File is saved in the directory.
Grammar¶
The grammar in technical writing is the most important ingredient. The proper usage of grammar avoids translational difficulty and incorrect interpretation. You should verify that your sentences are grammatically correct. Making grammatical errors in your information lessens your credibility and the credibility of your company.
Use active voice¶
Active voice is clearer than passive voice. Active voice is easy to comprehend. Active voice puts the performer of an action at the beginning of a sentence. If you want to emphasize who or what performs some action, use active voice.
Active - The developer develops the software.
Passive - The software is developed by the developer.
Certain situations may need passive voice. Use passive voice if you don’t want to emphasize who or what performs the action. If the action or the receiver of the action is more important than the agent, use passive voice for the proper emphasis.
For example:
Original - The system saves the file to the database.
Revision - The file is saved to the database.
Use the present tense¶
Use the present tense. Present tense verbs help you keep your writing style active and direct. You should use the present tense for your verbs whenever possible. The present tense is easier to translate and more engaging. Use the past or future tense only when the present tense would be misleading or illogical.
For example:
Original - The Web pages were uploaded during the installation.
Revision - The Web pages are uploaded during the installation.
Make note of subject-verb agreement¶
A verb must agree with subject in person and number. Use plural verb for plural subject. Similarly, singular verb for singular subject.
For example:
Original - Interviews is one of the way to collect data and allows researchers to gain an in-depth understanding of participants.
Revision - Interviews are one way to collect data and allow researchers to gain an in-depth understanding of participants.
Write in first person perspective¶
The technical document helps the user complete the task at hand. Therefore, in order to walk through the steps/instructions, TW needs to think from the perspective of first person and writing in second person.
Deciding whether to write in the first, second or third person depends on how formal you want the document to be.
First person – I, me, we
Second person – You
Third person – He, she, they, them
For example:
Original - Click. This feature helps to perform the task.
Revision - You must click. This feature allows you to perform the task.
Check relative pronoun¶
Use “that” with restrictive clauses¶
A restrictive clause introduces information that is necessary to the meaning of the sentence. The meaning of the sentence is incomplete without restrictive clause. Therefore, don’t put commas around a restrictive clause. Many style guides recommend using “that” with restrictive (or essential) clauses.
For example:
Original - The apple tree, which produced no apples last year, has loads of blossom.
Revision - The apple tree that produced no apples last year has loads of blossom.
Use “which” (plus commas) with nonrestrictive clauses¶
Nonrestrictive clauses tell you something about a preceding subject, but they do not limit, or restrict, the meaning of that subject. Even if you drop the clause, it doesn’t affect the meaning of the sentence. Easy method to recognize non-restrictive clauses is that they are used around commas.
For example:
Non-restrictive Clause -
Ron, who scored highest, is waiting at the door.
Without Non-restrictive Clause - Ron is waiting at the door.
Check indefinite pronoun¶
Pay close attention to indefinite pronouns such as all, some, none, each, several, many, either, and neither.
Each, either, and neither are always singular.
Few, both, several, and many are always plural.
All, any, most, and some can be singular or plural depending on the noun in the of phrase that follows them.
For example:
Original - Each of the files are stored in the directory.
Revision - Each of the files is stored in the directory.
Check appositives¶
An appositive is a noun or pronoun element that immediately follows another noun element in order to define or further identify it. An appositive is said to be “in apposition” with the word or phrase to which it refers. Commas frame an appositive unless it is restrictive. A restrictive appositive cannot be removed from a sentence without obscuring the identity of the word or phrase that the appositive relates to.
Restrictive appositive - The popular US president John Kennedy was known for his eloquent and inspirational speeches.
Non-Restrictive appositive - John Kennedy, the popular US president, was known for his eloquent and inspirational speeches.
Replace prepositional phrases with adverbs¶
A strong adverb may replace a weaker prepositional phrase.
For example:
Original - The approval of the plan was given by the committee.
Revision - The committee approved the plan yesterday.
Use ellipses in task topics¶
A grammatical ellipsis (sometimes called an omission) occurs when part of a clause is left understood and the reader is able to supply the missing words. In colloquial speech, an ellipsis is useful to avoid repetition, shorten the message, and make it easier to understand. It’s particularly appropriate for commands and exclamations, and especially when asking or answering a question whose complete answer would essentially repeat the question.
For example:
Original - Can you please click the Next button.
Revision - Click Next.
Use transitive verb with direct object¶
A transitive verb must have a direct object to indicate the receiver of the action. Do not use a transitive verb without a direct object. Either supply a direct object or use an intransitive verb instead.
For example:
Original - Your document will not print.
Revision - The printer cannot print your document.
Punctuations¶
Punctuation is governed by its function, which in ordinary text is to promote ease of reading by clarifying relationships within and between sentences. Make sure the punctuations used are correct and appropriate.
Periods¶
A period marks the end of a declarative or an imperative sentence. When an entire independent sentence is enclosed in parentheses or square brackets, the period belongs inside the closing parenthesis or bracket. When matter in parentheses or brackets, even a grammatically complete sentence, is included within another sentence, the period belongs outside .
Commas¶
Commas usually denotes a slight pause. Effective use of the comma involves good judgment, with the goal being ease of reading. When the context calls for a comma at the end of material in parentheses or brackets, the comma should follow the closing parenthesis or bracket. A comma never precedes a closing parenthesis. Remember to use commas around nonrestrictive clauses.
For example:
Original - In Windows you can run many programs.
Revision - In Windows, you can run many programs
Semicolons¶
Semicolons are similar to periods in that semicolons must be followed by a complete sentence (except for items in a list). The part of the original sentence after the semicolon is not a complete sentence because it doesn’t have a verb.
For example:
Original - The client software creates specific output files; such as XML files and SQL files.
Revision - The client software creates specific output files such as XML files and SQL files.
Apostrophes¶
Use apostrophes to form the possessive case of nouns and to indicate a missing letter in a contraction.
Em-dashes¶
Em-dashes are compelling punctuation marks, rich with punctuation possibilities. An emdash represents a longer pause—a bigger break—than a comma. If a comma is a quarter note rest, then an em-dash is a half-note rest.
Tone¶
Tone conveys how a piece of writing sounds or how it feels to the user. Tone expresses the writer’s attitude toward the subject and the audience.
Use appropriate and consistent tone¶
An appropriate and consistent tone helps the user do the task, learn the concepts, or make the right decisions without needing to interpret your rhetoric. You must understand the audience and the purpose for the information to achieve the tone that works best for a particular situation.
For example:
Original - Of course, you might not be able to type if you don’t first install your software.
**Revision **- Before you type, you must configure your software.
Use straightforward, noncolloquial style¶
Sometimes TW use colloquial or idiomatic expressions to create a friendly, less intimidating tone. However colloquial and idiomatic expressions becomes difficult for translators to translate accurately due to unavailability of equivalent word in their language. To help translators create unambiguous translations, use a straightforward, noncolloquial style.
For example:
Original - This section describes humongous ways to learn how to add logic to one path of execution for your Decision node, so hold on.
Revision - This section describes various ways to learn how to add logic to one path of execution for your Decision node.
Maintain an authoritative tone¶
Technical information is sometimes written with a pretentious tone. Sometimes TW use complex sentences, abstract technical terms, and a wordy style to be seen as credible and authoritative. This tone can be confusing and intimidating. Therefore, try to maintain an authoritative tone without being pretentious.
For example:
Original - One must recognize that pollution could be reduced by the new National Clean Air Programme (NCAP) measures.
Revision - The new National Clean Air Programme (NCAP) measures can reduce pollution.
Mood¶
Mood describes the TW’s attitude toward the action. The unaware choice of verbs expresses different mood such as the indicative, imperative, or subjunctive.
Use imperative mood for procedures¶
The imperative mood is the verb form used to make a command or a request. With its implied you, the imperative mood addresses the user and clearly identifies the action that the user should perform. Use the imperative mood for task information.
For example:
Original - It is unlikely that you are supposed to move the file to another location.
Revision - You have to move the file to another location.
Use indicative mood to state facts¶
An indicative mood is a form of the verb that either indicates to a fact or denies a fact. Use mainly the indicative mood for conceptual and reference information. Use indicative mood to state facts and opinions.
For example:
Original - The system needs to be checked.
Revision - Check the system.
Avoid subjunctive mood¶
The subjunctive mood expresses wishes, doubts, and desires. A subjunctive statement can confuse users and can be difficult to translate into languages that do not have the equivalent verb quality.
For example:
Original - You should have saved the file before closing.
Revision - Save the file before closing.
Style¶
Style guidelines helps to ensure that writers working on related information do not introduce variations that will create inconsistent presentation. In order to form a pattern and visual cues, every organization follows a style guide. There are industry standard templates(pre-made designs and documents that can be customized) and boilerplate text (Boilerplate text is a standardized text, copy, documents, methods, or procedures that may be used over again without making major changes to the original) available to use for maintaining the style. TW’s are advised to make sure that the document follows particular style. To check and decide on conventions, consider the following guidelines for maintaining the structure of language:
- Overview/Introduction
- Steps
- Reference
Make sure the technical document has an overview section, followed by proper steps/instructions and all the necessary references are provided.
For example:
MS Style - Click Ok. The Refresh tab appears.
MSTP Style - Click Ok. The Refresh tab is displayed on the screen.
Chicago Manual of Style -
Summary¶
Make sure technical document is grammatically correct and free from typos. All the terminologies used are uniform. Maintain the grammar and style. Keep updating yourself with the new style guides and competent technology adoption for best user experience.
References: