Appendix B: Important Writing Tips

This appendix contains a collection of tips that address common problems in writing, grammar, punctuation, and word usage that are not covered elsewhere in this guide.

Common mistakes with apostrophes

Do not use an apostrophe when pluralizing numbers and acronyms. For example:

Right: There are 100s of ATMs in the city.

Wrong: There are 100’s of ATM’s in the city.

Additionally, do not use “it’s” to show the possessive for “it.” “It’s” always means “it is.”

For example:

Right: The company posted its earnings.

Wrong: The company posted it’s earnings.

Correct usage of periods and spaces

Use a single space after a period, not two spaces. Traditionally, you would use two spaces if you were using a monospace font (like Courier) instead of a proportional font (like Arial), but common usage eliminates the second space even with monospace fonts. A second space increases the chances of “rivers” of white space running through your paragraph, which is visually distracting.

Put the period before end quotes unless you’re quoting a literal string:

Right: This page is called a “view.”

Right: In the box, enter “server1”.

Put the period outside the parentheses unless it’s a complete sentence:

Right: Use the Markup tool (the pencil icon).

Right: Use the Markup tool. (The tool is represented by a pencil icon.)

Writing numbers

• Use words for numbers less than 10, such as “three catalogs.”
• In a list that mixes numbers less than 10 with those greater than 10, use numerals for all, such as “The script runs at 6, 9, and 12 minutes after the event.”
• Use numerals with units of measurement, such as “4 inches,” “16 bits,” and “500 MHz.”
• Use a numeral with “percent,” and be sure to use the word “percent” instead of the symbol in sentences, such as “14 percent.” Use % in tabular data only.
• Always spell out ordinal numbers, such as “first” instead of “1st”. Only use the abbreviation in graphics, tables, and charts with limited space.
• Use decimals instead of fractions where possible, such as “1.5” instead of “1-½”.

Avoid the passive voice

Wherever possible, use the active voice so that it’s clear who/what is performing the action. If you’re using a form of the verb “to be,” you are likely using the passive voice.

For example:

Passive: The widget module is installed.

Active: Your administrator installs the widget module.

Passive: A mistake was made.

Active: The user made a mistake.

Avoid misplaced modifiers

Misplaced modifiers are words, phrases, or clauses that seem to refer to or modify an unintended word because of the placement in a sentence. For example, “When young, circuses appeal to us all” makes it sound like when circuses are young, they appeal to us all.

To avoid this problem, make sure the modifier (e.g., young) is as close as possible to the word it’s modifying (e.g., we). For example, you could rewrite the sentence as “When we are young, circuses appeal to us al” or “When young, we all find circuses appealing.”

Placement of “only” and other adverbs in a sentence

Place adverbs such as only, nearly, almost, ever, scarcely, merely, too, and also as close as possible to the word modified--usually directly before it. Putting the adverb in the wrong position can change the entire meaning of the sentence.

Examples:

The message appears only if you are logged in as Administrator.

(Not if you are logged in as another role.)

The message only appears if you are logged in as Administrator.

(It doesn’t flash, glow, or do anything else visually.)

Only Matt liked the candidate.

(No one else liked the candidate.)

Matt only liked the candidate.

(Matt didn’t love the candidate and might not vote for him.)

Matt liked only the candidate.

(Matt didn’t like the candidate’s nominee for VP.)

Right: Our list of customers numbers almost 500.

Wrong: Our list of customers almost numbers 500.

Referring users to other sources

Refer a user to another page by telling them to “see” that page. To refer them to a web site, use “go to”. Do not use “refer” or “refer to”.

For example:

Right: For more information, see Proxy Services.

Right: For more information, see the Governance Registry documentation.

Right: For information on other WSO2 products, go to www.wso2.com.

Wrong: For more information, refer the Governance Registry documentation.

Wrong: For more information, refer to the Governance Registry documentation.

Put the subject of the sentence first

To make the sentence clear and active, put the subject first. For example, in both of the following sentences, “user management functionality” is the subject, but the first sentence is better because it puts the emphasis on what matters most in the sentence:

The user management functionality is one of the powerful features of WSO2 Identity Server.

One of the powerful features of WSO2 Identity Server is the user management functionality.

Remove extraneous wording

Building on the previous example, instead of saying it’s one of the powerful features, we should just say it’s a powerful feature:

The user management functionality is a powerful feature in WSO2 Identity Server.

Also, avoid repeating yourself, and tighten things up to the shortest possible sentence you can. For example, consider this excerpt:

User management comes bundled with the WSO2 Carbon platform and facilitates the management and control of user accounts and roles at different levels. Since it is integrated into the core Carbon platform, user management capability is available by default in all WSO2 Carbon-based products.

We can tighten this up quite a bit:

User management is available by default in all WSO2 Carbon-based products.

We have already defined user management in a previous paragraph, so this sentence is now focused just on the fact that user management is part of the WSO2 products by default.

Capitalization after a colon in a sentence

Do not capitalize after a colon within a sentence except when a colon introduces a direct quotation or when the first word after the colon is a proper noun or an acronym.

Here are three examples:

There are two main types of transports: blocking and non-blocking.

(No capitalization after the colon)

The Guide to Transports describes non-blocking transports as follows: “The worker thread that sends the request does not wait for a response, thus improving server performance.”

(Capitalize a direct quote that comes after a colon)

Blocking transports improve reliability: WSO2 EI waits for the response before it continues processing requests.

(Capitalize a proper noun that comes after a colon)

Commonly misused words

This section describes words that are commonly confused or misused.

Which vs. what

If you are trying to make a choice, use “what” when there is an unknown number of possibilities for the answer. For example: “What problem are you trying to solve?”

Use “which” if you are choosing between a limited number of items. For example: “Which type of device do you have: iOS or Android?”

Often, “which” or “what” can be used for several choices, depending on what is in the speaker’s mind:

For example:

A: “Which bus goes into the center of town?”

B: “What bus shall I take?”

Both sentences are fine. The speaker is probably thinking about fewer buses in sentence A than in sentence B.

Can vs. might vs. may

Use “can” to indicate something is possible. (“You can change your password at any time.”). Use “might” when something is conditional. (“Depending on your configuration, you might need to change your password.”) “May” is supposed to be used to indicate permission. (“Only administrators may change a user’s password.”) However, because “may” is often also used to mean “can” or “might,” typically use “can” or “might” instead to avoid confusion. For example, “Only administrators can change a user’s password” and “You might want to change your password" instead of "You may want to change your password.”

Using “e.g.” and “i.e.”

The Latin abbreviation “e.g.” is synonymous with “for example” or “such as” and is used before an example, whereas “i.e.” is synonymous with “that is” and is used before an explanation. Best practice is to use the English equivalent, but if you do use the Latin abbreviation, be sure to use a comma after the second period.

For example: Right: Alex bought many items, e.g., hammers, shovels, and saws. Right: Alex bought many items, such as hammers, shovels, and saws. Right: Alex bought the whole store, i.e., a great many items. Wrong: Alex bought many items, i.e. hammers, shovels, and saws.

Imply vs. infer

Imply means to suggest; you imply something with your words and actions. Infer means to assume or deduce; you infer something from another person’s words or actions.

For example:

Vera implied we were not invited to her party. I inferred from her remarks that we were not invited.

Advice vs. advise

“Advice” is the noun, and “advise” is the verb.

For example:

Right: For more advice on performance tuning, see Performance Tuning.

Right: Please advise WSO2 if your contact information changes.

Wrong: I gave the user advise on the architecture.

Wrong: I will advice the user on their architecture.

Use “way”, not “ways”, for distance

Do not use “ways” for distance. For example:

Right: I live a short way from here

Wrong: I live a short ways from here

Irregardless is not a word

“Irregardless” is not a word. Use “irrespective” or “regardless” instead.

For example:

Right: They will move ahead regardless (or irrespective) of the warnings.

Wrong: They will move ahead irregardless of the warnings.

Use “functionality”, not “functionalities”

Wrong: The product contains the following functionalities.

Right: The product contains the following functionality.

“Cannot” is one word

Right: You cannot select that option.

Right: You can’t select that option.

Wrong: You can not select that option.

“Sign in” vs. “Sign-in”

“Sign in” is the verb form. Use this form on buttons and anywhere you’re telling the user to sign in. “Sign-in” is the adjective form and modifies a noun. However, the Microsoft Writing Style Guide says to avoid using "sign-in" altogether and to focus on the action instead.

For example:

Right: Sign in with your user name.

Wrong: Sign-in with your user name.

Right: Sign in to access the application.

Wrong: Access the application with your sign-in name.

“Sign in” vs. “Log in”

“Sign in” and "Sign out" are preferred over “Log in” and "Log out". Only use "Log in" and "Log out" if that's the wording that's used in the user interface.

Plug-in vs. plugin

Use plug-in.

“Orientated” is not a word

The correct word is “oriented”.

For example:

Right: You should attend orientation to become oriented to our policies.

Wrong: You should attend orientation to become orientated to our policies.

“Reoccurring” is not a word

The correct word is “recurring.”

For example:

Right: Consider both one-time and recurring expenses.

Wrong: Consider both one-time and reoccurring expenses.

“Further” vs. “farther”

Typically, use “farther” for physical distance (“We drove 10 miles farther down the road”) and use “further” to mean greater extent (“We’ll look into it further”, “No further comments”), “additional” (“Further bulletins came in”), or “moreover” (“Further, you hurt his feelings”). Historically, “further” has also been used interchangeably with “farther” for physical distance, but modern usage prefers “farther” for distance.

“Imbedded” is not a word

The correct word is “embedded.”

For example:

Right: Some rules are simply embedded in the source code.

Wrong: Some rules are simply imbedded in the source code.

Affect vs. effect

Both of these words can be used as nouns and verbs, but the meanings are different. Usually, use “affect” as a verb (“This setting affects your permissions”) and use “effect” as a noun (“The effects of this setting vary”). “Effect” can also be a verb; in this context, it means to create, as in “He will effect new laws”, meaning he will create new laws, whereas “He will affect new laws” means he will have an impact on new laws. Lastly, when “affect” is pronounced with the accent on the first syllable (AF-ekt), it is a noun meaning display of emotion, as in “His bland affect hid his real feelings”.

Utilize vs. use

Typically, “use” is the correct word. “Utilize” is appropriate only when you are referring to getting practical or profitable use from something. For example, “I was not able to use the computer” means that I was not able to operate it, whereas “I was not able to utilize the computer” means I was not able to find a good use for it. When in doubt, use “use.”

For example:

Right: Developers use many tools.

Wrong: Developers utilize many tools.

ID vs. Id

The abbreviation for “identification” is “ID” (two capital letters). “Id” with a lowercase “d” is a psychology term.

For example:

Right: Enter the user ID. Wrong: Enter the user Id.

Indexes vs. indices

Both are correct. “Indexes” is preferred in technical writing.

Less vs. fewer

Use “fewer” for things that can be counted (“fewer than four presentations”). Use “less” for things of measurable extent (“less paper”), or before plural nouns that denote measure of time (“less than three weeks”), amount (“less than $400”), or distance (“less than 50 miles”). Quantity should use “fewer,” e.g., “10 items or fewer,” NOT “10 items or less.”

Whether vs. if

The word “if” is often mistakenly used as a substitute for the word “whether”. Use “if” to express a condition. Use “whether” to express alternatives.

For example:

Right: Add buttons if the client requests them.

Right: They didn’t know whether to use a button or a check box.

Wrong: They didn’t know if they should use a button or a check box.

Avoid gendered pronouns

Avoid writing “he or she”, “s/he,” etc. wherever possible. Instead, use the second person “you” or the plural. In cases where you must refer to a single person, it is acceptable to use “they”, “them”, and “their” as the singular pronoun.

For example:

Right: When you sign in, enter a password.

Right: If you have the user’s device, you can scan the QBR code.

Right: When users sign in, they enter a password.

Acceptable: If the admin has your device, they can reset it for you.

Wrong: When a user signs in, he or she enters his/her password.

Avoid ambiguity

Place modifiers and pronouns carefully. “I only lent him a copy” could mean it was only a copy, not the original, or it could mean it was only a loan, not a gift. Also, in the sentence “The editor said she failed the test” does not clarify who “she” is. Is “she” the editor herself or someone else?

Avoid words that can have two meanings. For example, “There was a lot of conversation about him” could mean there was noise in the room or that people were talking about him.

Principal vs. principle

A “principal” is a key person in an organization, e.g., “Alex is a principal at the firm.” A “principle” is an important fact or rule, e.g., “Our decisions are guided by our principles.”

Counsel vs. council

When you are referring to someone who gives advice or the advice they give, the correct spelling is counsel. When you are referring to a board or group of people, the correct spelling is council.

For example:

Right: The legal counsel will counsel the members of the recruiting council on how to avoid illegal hiring practices.

Wrong: The legal council will council the members of the recruiting counsel on how to avoid illegal hiring practices.

More than vs. over

Use “more than” to refer to quantifiable figures and amounts. Use “over” to refer to a spatial relationship or position, or in a comparison in which “more” is already used.

For example:

Right: You can copy more than 1000 songs.

Wrong: You can copy over 1000 songs.

Right: After you compress your drive, your disk will have over 50 percent more free space.

Wrong: After you compress your drive, your disk will have more than 50 percent more free space.

Right: He flew more than 10,000 passengers.

Wrong: He flew over 10,000 passengers. (Unless he physically flew over them.)

A lot vs. alot vs. allot

The phrase “a lot” (meaning “to a considerable quantity or extent”) always consists of two words. Do not spell this phrase as one word (alot). Do not confuse this phrase with the verb “allot” (meaning “to distribute or assign a share of something”).

For example:

Right: He bought a lot of software.

Wrong: He bought alot of software.

Wrong: He bought allot of software.

Right: He will allot half his time to training and half to documentation.

Since vs. because

In spoken English, people often use “since” to mean “because.” For example: “Since you’re already here, you might as well stay.” However, to avoid ambiguity in technical writing, do not use “since” to mean “because.” Instead, use “since” to refer to time, and use “because” to refer to causality.

For example:

Avoid: I can download files quickly since I installed the software.

Better: I can download files quickly because I installed the software.

If you can insert the phrase “the time that” after “since,” it’s the correct choice.

For example:

Since [the time that] we started using WSO2 EI, our integration has been a snap.

Ensure vs. insure vs. assure

“Ensure” means to make certain. “Insure” means to protect against loss. “Assure” means to give someone confidence; the object of this verb should always refer to a person.

Examples:

I want to ensure (make certain) that nothing can go wrong tomorrow.

I want to assure you (give you confidence) that nothing will go wrong.

I want to insure this necklace (protect it against loss) for $5,000.

Of vs. have

Do not use “of” instead of “have” in verb forms. The correct forms are could have, would have, should have, might have, may have, must have, ought to have, and so forth.

For example:

Right: What could have happened?

Wrong: What could of happened?

Serve vs. service

People are served, whereas things are serviced.

For example:

We take great pride in the way we serve our customers. For a small additional charge, we will service the equipment for a full year.

Tack vs. tact

Use “tack” to mean changing direction. Use “tact” to mean being considerate.

For example:

We will have to take a different tack in our negotiations.

Be sure to use a great deal of tact when you reply.

All together vs. altogether

All together = all in a group

Altogether = entirely

For example:

The papers are all together in the binder.

He is altogether too junior for the position.

Appraise vs. apprise

Appraise = set a value on

Apprise = inform

For example:

We would like to appraise the ring.

I will apprise you of any further developments.

A while vs. awhile

“A while” is a noun meaning “a length of time”.

For example:

I slept for a while.

(Compare with “I slept for a bit” and “I slept for three hours”)

I was away from my desk for a while.

(Compare with “I was away from my desk for two minutes”)

"Awhile" is an adverb, meaning “for a time,” or literally, “for a while”.

For example:

I slept awhile before dinner.

(Compare with “I slept deeply before dinner” and “I slept badly before dinner”.)

The words can be used almost interchangeably in some cases, but "a while" needs to be preceded by a preposition like “for” (“I slept for a while”) or followed by an adjective like “ago” (“I left work a while ago”) or “back” (“I ran into him a while back”).

Bad vs. badly

Use the adjective “bad” (not the adverb “badly”) after the verbs “feel”, “seem”, and “look.” For other verbs, use the adverb “badly.”

For example:

I feel bad about the mistake.

I didn’t want to look bad in front of the others.

She seemed bad when I visited her in the hospital.

He was hurt badly in the accident.

She performed badly that day.

“Up-to-date” is one word

“Up-to-date” has hyphens and is written as one word, even when it is not followed by a noun.

For example:

Get up-to-date information in the release notes.

The software is up-to-date.

Inbuilt vs. built-in/built in

“Inbuilt” is primarily a British term that sounds foreign to many Americans. Use “built-in” (before a noun) and “built in” (when standing alone) instead.

For example:

Right: The application has built-in monitoring capabilities.

Right: The application has monitoring capabilities built in.

Wrong: It was an excellent and well thought out presentation.

Startup vs. start-up vs. start up vs. start

Use “startup” as a noun or as an adjective. Use “start” instead of “start up” for the verb. Do not hyphenate “start-up”.

For example:

Right: At startup, the server loads the library files. (noun)

Right: Use the startup scripts. The startup screen appears. (adjective)

Right: Start the server. Wait for the server to start. (verb)

Wrong: At start up, the server loads the library files.

Wrong: Use the start-up scripts. The start-up screen appears.

Wrong: Start up the server. Wait for the server to start up.

Setup vs. set up

Similar to “startup” and “start up”, use “setup” as a noun or an adjective, and use “set up” as a verb.

For example:

Right: This setup gives you maximum performance. (noun)

Right: The setup script helps you get started quickly. (adjective)

Right: You must set up your configuration before you begin. (verb)

Wrong: This set up gives you maximum performance.

Wrong: The set up script helps you get started quickly.

Wrong: You must setup your configuration before you begin.

Comprise vs. compose

These words are often confused and used incorrectly, so it’s best to avoid them. “Comprise” is synonymous with “include”, as in “The pie comprises eight slices”, which is synonymous with “The pie includes eight slices”. “Compose” means to make up or be the basis of, as in “These features compose the product” or “These features make up the product”. The tricky part happens when writers use the passive voice and are not sure whether to use “of” or “by” after the word. The correct usage is “The product is composed of these features” and “These features are comprised by the product”.

To avoid confusion, avoid “comprise” and “compose” and use “include” in the active voice: “The product includes the following features”. If you want the parts to be the subject of the sentence, use “These features make up the product”, but generally it’s clearer to make the whole the subject as in the former example. See also http://www.dictionary.com/e/comprise-vs-compose/.