Search this site

Contact Us

 Email info@publishingsmarter.com
 Phone 905 833 8448
Resources‎ > ‎Articles and Books‎ > ‎

Editing tips

I do a lot of writing. Emails, website articles, magazines, responses to groups, training manuals, and more. In writing this I often review my materials to ensure that I follow the best practices that I try to teach to others. However, it is not always the case that I succeed. Sure, spell check is great, but there is a lot more to be added to the process. Part of this includes good editing.

There are many people who help with this, and the feedback they provide is invaluable to making content better. To that end, here are a few of the more common things I've been told over the years. They are in no specific order.

Titles in documents

Tip: It’s easier to see inconsistencies in a generated TOC than in the text, so use your lists, even though errors have to be fixed in the source.

Chapter titles should contain parallel wording with the corresponding tutorial titles.

For example: In a chapter, the word “indexes” is used; in the matching tutorial it is “indices”). Although both are acceptable, they should be consistent, and “indexes” is preferable.

Section titles do not have parallel phrasing.

For example: One chapter could have three subtopics titled [Apply bold], [Apply italics], and [Underlining text]. This creates titles that are flawed (the last does not follow a [Verb noun] combination).

Passive voice

This is not so much an editing comment as a comment on writing style: avoid passive voice and instead use active voice.

Singular and plural

Don’t use (s) to mean “singular or plural”. It’s awkward, and causes trouble with verbs. If you use plural, and the user is working with a single concept, he or she will understand the instructions anyway.

Procedure numbering

Many editors would tell you that you shouldn’t use numbering for procedures that have only one step (they would say that you should use a bullet instead). However, I disagree, because I think numbering helps the user identify this as a procedure. This idea enforces consistent messages being delivered. A user can scan a page and find a task very quickly.

Dialogs appear or display

Watch out for sentences that read The [GenericName] dialog displays. Although many people use this, it is not correct. The verb display is transitive and therefore needs an object, as in The shopkeeper displays his merchandise.

To describe what happens when you click something to make a dialog appear on the screen, use the phrase The [GenericName] dialog appears, because appear is an intransitive verb.

Sometimes you may have The [GenericName] dialog is displayed, which is not wrong grammatically, but it is passive, which is not ideal. Try to be consistent and use appears.

Variety of

This phrase may be used a lot. So is the phrase a wide range of. This is unfortunate; it causes a lot of trouble when it is the subject of a sentence. This is because the concept of variety is plural, but the word is actually singular.

It is strongly suggested that you replace a variety of with several, many or numerous, and make sure the verbs are plural. In some cases, you may even be able to delete it altogether without changing the meaning of the sentence.

For example: In the sentence A variety of file extensions are used on the Internet the plural verb are (for the plural noun extensions) is used. However, you need the singular verb is (for the single noun variety).

Dialog names

Don’t add box to dialog.

Punctuation

If the serial comma is used, then be consistent with it. I try to be.

Other consistency issues

In each of the following items, the bold item in my list is the preferred spelling. In some cases, I marked corrections in pencil in the document; in other cases, I didn’t. It’s best to search and replace throughout the document.

  • online vs. on-line
  • popup vs. pop-up
  • % vs. percent
  • double-click vs. double click
  • dialog vs. dialog box
  • file name vs. filename
  • regarding vs. in regards to
  • period vs. full stop
  • programming vs. programing
  • C:\ vs. c:\


That versus which

That and which indicate different things. Do not use them interchangeably.

That is restrictive. That introduces a phrase essential to the meaning of the word it modifies. The phrase is not set off with commas.

Which is nonrestrictive. Which introduces a phrase that is not essential to the meaning of the sentence. The phrase is set off by commas.

Tip: Search for occurrences of which that are not preceded by in, of, at, by or a comma, and fix accordingly.

Consider two examples of similar content:

Incorrect

  • Our new interface, that has been recently modified, is included in version 1.1.
  • Items which contain subitems have a plus sign next to them.
  • The folder which contains a subfolder is called sales.

Correct

  • Our new interface, which has been recently modified, is included in version 1.1.
  • Items that contain subitems have a plus sign next to them.
  • The folder, which contains a subfolder, is called sales.

Dangling modifiers, infinitives, and participles

Dangling modifiers are an embarrassing problem. Once you know what a dangling modifier is, you will never dangle again.

A modifier, by definition, attaches to something. If the thing that it attaches to does not appear in the sentence, then the modifier dangles.

Dangling modifiers can be gerunds, infinitives, or participles. They usually appear at the beginning of a sentence, but not always.

Dangling modifiers

Consider two examples of similar content:

Incorrect

  • By pressing the X icon, the system will be shut down.

Correct

  • By pressing the X icon, you shut down the system.
  • Shut down the system by pressing the X icon.

In the incorrect example, the dangling modifier By pressing the X icon has lost its subject: who presses the icon? In this sentence, the system is the only subject and the dangling modifier attaches to it creating the meaning the system presses the icon. However, we know that the system does not press the X icon.

The best way to get rid of a dangling modifier is to rewrite the sentence to include the implied subject. Avoiding the passive voice often solves dangling modifier problems.

Dangling infinitives

Consider two examples of similar content:

Incorrect

  • To complete the task, the system must be restarted.

Correct

  • To complete the task, you must restart the system.
  • To complete the task restart the system.

The first example is incorrect because the system is not going to complete the task, you are.

Dangling participles

Consider two examples of similar content:

Incorrect

  • Even after adding more data, the spreadsheet calculated as quickly as before.

Correct

  • Even after you added more data, the spreadsheet calculated as quickly as before.

The first example is incorrect because the spreadsheet did not add more data, you did.

Misused words

Then, than

Than (conjunction) is used in comparing. Then is an adverb meaning “at (or after) that time” or “in that case; therefore.”

Affect, effect

Affect (verb) means “to have an effect on.” Effect (noun) means “as a result, consequence, outcome.”

Tip: Effect can be used as a verb (less common), and means “to accomplish, to bring about.”

Here

Already, all ready

All ready means “fully ready”; already means “previously.”

As, because, since

For expressing cause, because is most precise; since and as may ambiguously convey either time or cause.

Among, between

Between implies two persons or things in a relationship; among implies three or more.

Only, just

Only and just depend on placement for their meaning. Choose your placement carefully and make sure the meaning you use is the one you intend.

While

Be aware that while has two meanings:

  1. You play chess while the television is on. (during)
  2. I play chess, while my brother prefers poker. (whereas)

So

So has two meanings. Make sure you use of so is clear and unambiguous. If the reader can interpret your sentence in different ways, reword.

For example: In the sentence CacheRestrict blocks the cache so the user cannot there are two implied meanings. These are CacheRestrict prevents the user from updating the cache by creating a block and CacheRestrict blocks the cache and, as a result, the user cannot update it. Use the correct sentence to avoid the use of so.

When, if

When and if are not interchangeable. Use when only when the event described is inevitable. Use if if the event is uncertain.

Whether, if

Use whether and if correctly. Whether conveys the sense of a question. If is used conditionally.

Can, may, might

Use can to denote capability or ability; use may and might for possibility.

Less, fewer

Fewer is always used when referring to anything that can be counted. Less is a word that indicates degree.

For example: This year we had less rain. This is due to fewer days with percipitation.

Number, amount

Number is used with countable nouns. Amount is used with collective or mass nouns.

For example: They bought a large number of toys for the holiday. Equipping a hospital ward with toys costs a large amount of money.

Comprise, compose

Comprise literally means “embrace” or “include”.

For example, a zoo comprises mammals, reptiles (because it “embraces” them) but animals do not comprise (“embrace”) a zoo. This means that our FrameMaker files do not comprise a FrameMaker book but that a book comprises files. Do not use the passive voice with comprise or compose.

For example: This configuration is comprised of one or more service stations. I composed a letter summarizing this.


Disclaimer

This article is written by me, but contains ideas from people who know a lot more about editing than I do. The tips are just a collection of ideas other people have mentioned in the past. Any errors are mine alone. I don't claim to be a master of the English language, but do try to listen to those who know better than me on how to use it.

Bernard Aschwanden


Comments