Writing Tips

[Last updated: 11-May-2018]

This page describes a number of topics on how to maintain consistency when writing documents.


General Wording Styles

Tables/Lists following a Heading - It is not good practice to start a section directly with a table or list, as it is wrong to assume that the reader knows what the contents of the table or list represents! Always precede a table or list with a description or an explanation about what is to follow. You cannot assume that every reader knows what the information is about!

Translation - Lost in Translation is a collection of words and phrases that are frequently incorrectly translated from French into English. It is important to note that the choice of the suggested English alternative is purely down to the context of the sentence.

Copyright and Registered Names - When quoting a company's name or product, make sure it is spelt correctly (with correct upper and lowercase characters). Use the Copyright (©) and/or Registered (®) symbols appropriately; for example, GORE® LYOGUARD®. I’m sure you or your company would not want to be standing in front of a judge for libel; incorrect spelling!

Consistency - Use consistent terminology throughout a document; i.e., if For example is used, do not include instances of e.g., and vice-versa.

Wording Styles in Instructions

The following table contains a selection of typical words/phrases that often lead to lack of clarity and ambiguity, and also shows how the words/phrases can be written more clearly.

according to the usual procedure Cross-refer to additional applicable instructions
as far as is necessary Specify what is necessary
as required Specify when the case applies
Double negative Simple affirmation
if possible or as far as possible Clear description; Define exceptions
if required Specify when something is required
in general or mainly Specify the exceptions
in specific cases Specify when the case applies
where applicable Specify when the case applies
sufficient Specify the quantity or time, including permissible tolerances
Long, convoluted sentences (see Gunning Fog Index) Short, precise sentences
Long enough or Sufficiently long x to y Minutes (or Hours/Days/Months)
must From a pharmaceutical perspective, it is not permitted to use the word must in a guideline document, as the word can be audited. Instead, use phrases similar to has to, needs to or it is essential that
Not to be used in lists: and so on or etc. Exhaustive list. The user may not be aware of other possible alternative values
one The responsible person needs to be clearly identified

Managing Images

It is important to be aware how different image file formats can affect the size of a file; especially if a company's e-mail system has a ceiling on the size of e-mail messages. Images come in many different formats: Joint Photographic Experts Group (JPEG) and Graphics Interchange Format (GIF) are compressed formats, whereas the Windows Bitmap format is not.

The different formats have different uses. The following table shows the different image types, and how to best utilise them. It also provides additional information on how/when/why to use the different image types.

.jpeg The Joint Photographic Experts Group format supports up to 16 million colours. Therefore, it is ideal for photographs where a large number of colours is required.

Note: Avoid inserting raw images (those taken directly from a camera) into documents, as the size of these files can easily be in excess of 4 or 5 Mb. Thus, the size of the document can be dramatically increased if the document is highly illustrated. To solve this issue, use an image editing utility to reduce the physical size of the image.

.png The Portable Network Graphics format also supports up to 16 million colours. Therefore, it is ideal for producing logos, and also flowcharts, presentations and illustrations (for example, screen captures). It is a better format than the .gif format.
.gif The Graphics Interchange Format supports up to 256 colours. Therefore, it is ideal for producing simple logos and/or greyscale flowcharts, where the number of different colours is relatively low. The format also supports animation.
.bmp Avoid this format in a document at all costs. These files are over-inflated and contain a lot of empty space; a bit like Gruyère cheese! If .bmp files are used, it is hightly probable that, when sending the document via e-mail, the e-mail application could fail to send it because it is too large; especially if a company's e-mail applicatrion has a limit on the size of e-mail attachments.

Personal experience has seen an e-mail message, containing a Word document (of over 80 Mb), fail to be sent via e-mail. By extracting the original .bmp images, converting them to .jpg (using an image editor program), and re-inserting the smaller .jpg images back into the document, reduced the document to under 20 Mb. The attachment was then small enough to be sent through the company's e-mail application, being just under the company's 20 Mb limit for attachments.

.vsd Visio drawings. This format is ideal for producing flowcharts. To transpose a copy of the image from Visio into a document,
  • Create a Group of the required shapes
  • Copy the complete group
  • Paste the group into the destination document.

    If, however, the drawing is to be used in several different locations, it is wise to export the drawing to an image.

Capturing (Parts of) a Window To capture the contents of the whole screen, press <Print Scrn>.

To capture a specific window, select the window and press <Alt> + <Print Scrn>.

If using either of the above key combinations to capture a screen, avoid pasting the captured content directly into a document, as the resulting format is uncompressed. If there are many illustrations to capture, the receiving document could end up being extremely large! This can present difficulties with disk and e-mail quotas. Instead, paste the result into your favourite image editor (MS Picture Manager or Paint Shop Pro), Export (Save) the image as a .jpg or .png file, and Insert the new image into the destination document.

Instructions, Notes and/or References Do not place notes, instructions or references on an image. These items must be located within the document text. The reason being: if the instructions should change in the future, the image immediately becomes out-of-date and needs to be edited and reinserted, thus creating additional work! Also, if the update happens some time later, it is possible that the original image file is not available.
Scaling When illustrating a series of images, it is recommended that they are all resized to the same scale, keeping them all relative to each other (as in real life); for example, reduce all captured images to 50%. Thus, a simple pop-up ‘Yes/No’ confirmation pane is shown correctly, in relation to a full menu window.
Borders Use your favourite image editor to add a 10-pixel white border around each image. This will avoid the image(s) ‘colliding’ with any surrounding text, or other images.
Layout If possible, ‘centre’ the image(s) on the page; this produces a ‘balanced’ look within the text. Also,
  • Right-click the image and select Format picture
  • Click the Layout tab
  • Select In line with text and not In front of text. This ensures the image moves with the text, and also assists in preventing the image from ‘colliding’ with any surrounding text.

Grammatical Consistency

Consistency is important, as it can indicate a unified body. The following table describes some items that regularly get misrepresented and/or misspelt, particularly with written British English!

.
Abbreviations Do not create a section listing all abbreviation.
Instead, add abbreviations (in parenthesis) after the full meaning of the abbreviation at its first instance; for example, Service Level Agreement (SLA). For subsequent instances, only the abbreviation need be used.
It is standard practice.
Note: It is not necessary to include an abbreviation if a term is used only once in a document.
Do not enclose abbreviations in quotation marks, unless it is a true quotation; for example, VAT, not "VAT". For consistency purposes.
Plural abbreviations do not contain an apostophe; i.e., Business Instructiuons (BIs) and Standard Operating Procedures (SOPs).

Apostophes should only be used if the context is possessive.

For consistency purposes; for example,
The VIP's car (singular possessive) or
The VIPs' cars (plural possessive).

The one exception is “it’s” and “its”. “It’s” always means “it is” or “it has”.

[Tip] To have the correct spelling, change the “its” in the sentence to “his”. If it doesn’t make sense, then use “it’s”. For clarification, see Common Errors in English Usage - its/it's.
Abbreviations and Acronyms An abbreviation is a short form of a word or words; for example, BT or GSK.

An acronym, on the other hand, is a word formed from the first letters of the words that make up the name of something; for example, AIDS.
The words ‘abbreviation’ and ‘acronym’ are not always used correctly; they do not have the same meaning!
Alignment Different types of paragraphs and lists have/need different levels of indent. Standardise on the set indent measurements, for consistency purposes.
Ambiguity Do not write ambiguous terms or words. Write clearly and concise; see also Punctuation Ensure that what has been written is clear; for example,
I saw a bird using a telescope.
This can have two meanings:
  • I used a telescope to look at a bird
  • I saw a bird that was looking through a telescope.

Although the second possibility is probable, it is highly unlikely! Therefore, write clearly.
To avoid any confusion, write temperature, time, and other values as clearly as possible. For example, write:
  • 0°C to 2°C, and not 0°C-2°C; the second temperature is +2°C, not -2°C
  • 2½ hours or 2 hours 30 minutes, and not 2.5 hours; the duration could be interpreted as 2 hours 5 minutes.
In the United States, a slash (/) is referred to as a virgule! This could easily cause confusion to a French-speaking person, as a virgule (in French) is a comma (,)! Where the audience is global, always use International English, as (I'm pleased to say) not everyone in this world speaks American!
Bullet Symbols Rather than have a variety of bullet point symbols, create first- and second-level bulleted list symbols. Standardise on the bullets, to maintain consistency.

Do not use the same styled bullet symbol for different bulleted levels.

Captions Captions/titles to figues and tables (respectively) should be mandatory, not optional. They make a document easier to read, as well as being an aid to navigation.
Conventions Keys: see References
Embolden Commands: Click OK.
Place bolded keyboard labels inside angle brackets: Press <Ctrl> + <S>.
Embolden Menu Commands: Click File, New and then select Document + CR.
To maintain consistency.
Copyright and Registered Names When quoting a company's name or product, ensure it is spelt correctly (with the correct upper and lowercase characters). Use the Copyright (©) and Registered (®) symbols as appropriate. I'm sure company_name would not want the names of its products spelt incorrectly; just as you would not like your name spelt incorrectly!
Cross References Avoid the use of the words "above" and "below" (for example, "...as in the illustration below").

This can easily cause confusion, especially if there is more than one illustration, or another illustration is added on the same page at a later date; and the surrounding text is not updated accordingly (proof-read)!

Instead, add captions to all figures and tables, and apply cross-references to the captions. When using symbols, for example asterisks (*) to refer to external references, ensure that the external reference exists!

Always write the external reference(s) in Italics

Document Names - If referring to an SOP or Policy document, avoid using the document name. I don't know why, but some document names are horrendously long; they are a story in themselves! Instead, simply write its reference number; for example, SOP-645.

I have seen instances where the same document's name has been spelt three different ways!

Having more than one reference for the same item (be it a document name or description, etc.) creates additional maintenance, together with the risk that one reference gets updated and the others don't!
Date Format The date '04-05-06' can be interpreted in many way, depending upon where you are in the world: 04-May-2006, 05-Apr-2006, 06-May-2004 and 05-Jun-2004! To ensure clarity and consistency, use the international date format: dd-Mmm-yyyy; for example,
04-May-2006.
Decimal Marker A lot of countries (particularly on the mainland of Europe) use a comma as a decimal separator. For documentation having a global audience, use the full stop; for example, write 3.25 cm, not 3,25 cm.
Double Spaces Do not place double spaces between sentences. It can lead to mis-pagination and mis-spacing. With modern versions of word processing software (we no longer use typewriters!), proportional spacing is automatic. Besides, double spaces are not inserted after commas, so why is a full stop any different!?
Duplication Avoid text duplication; for example, "The following flowchart diagram. A flowchart is a diagram, so use either flowchart or diagram; not both!
External References Before adding an external reference, first ensure that it exists! Apply italics to the names of external references and publications; for example, Le Monde and The Encyclopaedia Britannica. It doesn't look very professional if a link to an external reference goes into a black hole!
Flowcharts Certain chart objects have certain functions (for example, terminator shapes to start and end the flowchart, and diamond shapes for decisions), see RF Flow. A rectangular object in a flowchart is a process operation. It can have multiple inputs, but only one output, otherwise, it becomes a decision!

I once saw an Astellas flowchart that had four connectors flowing (presumably) into a rectangular process object and one output. The flowchart simply did not make sense!

The flow in an illustration is usually from top to bottom. Therefore, when creating a flowchart, ensure it flows from the top of the page to the bottom. However, for the output of decision objects, it may be better to go from left to right. It is easier (and natural) to read from top to bottom. Therefore, do not ‘distort’ the flow by trying to get the complete flowchart on one page!

If the flowchart is longer than the page, split it (the flowchart) over two pages, rather than squeezing it onto one page.

Grammar Nouns that start a sentence without a direct article (a, an, it, the, etc), could be mistaken as being a verb, causing the sentence’s meaning to be totally changed or misunderstood; for example, the words ‘address’ and ‘draft’. This seems to be an American trait (failure)! For clarity, if a phrase and/or sentence starts with a noun, insert a preposition before the noun!

[In the past, I have had to read some sentences three or four times in order to understand them! That is crazy - and English is my mother tongue!]

Hard-Coding Use generic references to items that are likely to change. Do not hard-code specific references, as this causes increased maintenance of the document(s); for example:

How to map to the [device_name:] NT shared area
should read
How to map to the shared area.

The reason is if/when (for example) an NT server is migrated, upgraded to a different operating system, or even totally decommissioned, all references throughout the document(s) will need to be updated to reflect the change; thereby causing additional editing work.
Header Sheets Ensure that each document has a header sheet. It is better to see a header sheet (as the first page of a document), rather than a Table of Contents (TOC), or even the the first chapter!
In a validated environment, a header sheet can show information such as the document reference number, the date the document was approved and/or made effective, etc.
Hyphenation Be extra careful when using hyphens, as they (like commas) can completely change the meaning of a sentence. For example:
  • Twenty odd people (vingt personnes étranges)
  • Twenty-odd people (vingtaine de personnes).
Jargon and Slang Do not use jargon, slang or country-specific expressions, as, with an international audience, not every reader understands; for example, I've seen:
  • Breakouts (from prison? Actually, it meant a group session!)
  • Ready to ticket (purchase/issue/collect?)
  • Set off (an explosion, or depart?).
Ask yourself “Would someone in Outer Mongolia understand what I am writing?” as not everyone has English as their mother tongue! Therefore, imagine you are talking to a chimpanzee/monkey, and keep the language very low-level. Use simple, international English.
Lists Do not have single bulleted items! There is no such thing as a one-itemed list! Has anyone you know gone shopping with a shopping list containing just one item? I can imagine not many, if any! A list is "a series of names or other items written or printed together in a meaningful grouping or sequence so as to constitute a record." [dictionary.com] Therefore, do not create (bulleted) lists with one item. Instead, create a sentence around the item.
Do not simply add items to a list haphazardly. Unless there is a specific reason to the contrary, always sort lists in alphabetical, chronological, numerical and size order; it is easier to read and to locate the required entry.
There appear to be many variations on the type of punctuation (commas, semi-colons and full stops) placed at the end of each item in a (bulleted) list. Based on a number of style guides I have seen, it is preferred to only place a full stop at the end of the last item on the list.
Start each list item with an uppercase letter. For consistency purposes.
Long Sentences Avoid long sentences, as they can cause misunderstanding, and can be tiring to read. Information must be clear and consise. Refer to the Gunning Fog Index for more information.
Navigation When an instruction or commant states Go to Step n, ensure Step n exists! Ensure that the destination location is valid, especially where an external document is referenced!
Nouns (Collective) A collective noun (for example a company), should be referred to in the singular form, as it is a complete entity; it also takes a singular verb.
  • Wrong: Krono have three lines of business. They manufacture chemicals, paint and pharmaceuticals.
  • Right: Krono has three lines of business. It manufactures chemicals, paint and pharmaceuticals.
  • Right: KPMG provides excellent consulting services. It ranks among the world's top firms.
Additional collective nouns include: a football team, the management of a company, and a flock of sheep.
Nouns (Plural) When making a noun plural in French, the noun, the verb AND any adjective(s) are usually made plural. In English, it is only the noun that is made plural. To make a noun plural, an 's' is usually added to the end of the noun; for example, The red car... becomes The red cars.... However, like everything in life, there are exceptions! As they exist, the following English words can be used in both singular and plural forms.
  • Damage
  • Data
  • Equipment
  • Information
  • Sheep
  • Software
  • Waste
  • Weather
Numbers For numbers less than 10, write the number in full; for example, eight, and not 8. Do not mix digits with spelt numbers in the same context within the same sentence or paragraph; for example, seven out of 10 adults. Do not begin a sentence with a number or year; write the number or year in full.

Use a non-breaking space (<Ctrl> + <Shift> + <Space>) between a number and its unit; for example 25 cm.

Note: Unit symbols are unchanged in the plural form: 25 kg, not 25 kgs; see the SI Writing Style.
Pronouns There is a distinct lack of pronouns (I, you, etc.) now-a-days, making some text confusing and ambiguous; for example:

In either case, would like to confirm that these docs are OK to release for approval.

What on earth does this (American) statement mean?

One could be a question (without a question mark!), while the other could be a statement:

In either case, would you like to confirm that these docs are OK to release for approval
or
In either case, I would like to confirm that these docs are OK to release for approval

Punctuation Like prepositions, there is a distinct lack of punctuation now-a-days (particularly commas and semi-colons). For example:
“It is important that these guidelines are followed in order to remain compliant".
As it is written, this sentence could be interpreted in one of two ways:
...these guidelines are followed in order, to remain compliant.
...these guidelines are followed, in order to remain compliant.
Commas break sentences into manageable and unambiguous sections. They also allow the reader to take breaths!
Read the book Eats, Shoots and Leaves by Lynne Truss, from which I use an interesting example:
Now I must go and get on my lover.
Now I must go and get on, my lover.
References to Keys When writing references to keys of the keyboard, or parts of a screen display, ensure that the reference text:
  • Represents exactly what is shown on the key or the screen
  • Is enclosed in angle brackets
  • Is formatted in bold type.
This avoids confusion from normal text; for example:
<Backspace>
<Enter>
<Delete>
<F4>
<Shift>
<Tab>
Spaces In written English, there is no space between the last word of a sentence and a full stop, comma, colon, semicolon, question mark or exclamation mark. However, in written French, these non-alphanumeric characters (together with left and right Guillemets (« and »)) are usually separated from a word by a space. Because of this way of writing, these characters can sometimes end up being the only character on a line, or even a page!

From an English reading point-of-view, it can be difficult to read ‘translated’ text, especially when (because of the amount of text) these characters are forced onto the next line (or the next page). This situation can also potentially waste paper!

One way to avoid this scenario (When producing an English language document) is to ensure that the language is set to British English. It is also helpful to have an English style (QWERTY) keyboard. However, if an English keyboard is not available, the following keyboard commands can be used:
<Alt> + 34 Double quotes (") in place of guillemets
<Alt> + 36 Currency symbol for US Dollars ($)
<Alt> + 156 Currency symbol for British Pounds (£)
<Alt> + 171 One half (½)
<Alt> + 172 One quarter (¼)
Table of Contents (TOC) Some establishments have an optional TOC. A TOC is a mandatory part of a document! A TOC aids navigation throughout the document, especially in its paper format.
Terminology When describing screen captures, differentiate between screen, window and pane, as they are all different in size! The screen is the whole display, containing a number of windows; hence the name of the operating system!
Panes are usually smaller than windows and are driven (pop-up) by the parent application.
Version Identifiers A version number (for example 2.4) usually comprises two parts: a major release identifier (2) and a minor upgrade identifier (.4) respectively. Examples of applications where this applies includes EasyDoc, TechShare and SharePoint. A major release is a numbered copy of a file that has changed significantly since the previous version (for example, the re-writing or addition of a document's chapter). Each major release is identified by a whole number (1.x, 2.x, 3.x, etc.).

A minor upgrade is a decimal-numbered copy of a file that is in a stage of revision, or that has changed only slightly since the previous version (for example, the correction of a spelling mistake or grammatical error). Each minor upgrade is identified by a decimal number (x.1, x.2, x.3, etc.).

There is more information at Wikipedia

Tables

Due to the number of items for tables (particularly from a formatting point-of-view), I have put them in their own table.

Captions Apply captions to all tables. This improves navigation and understanding.

Terminology

Consistency is important, as it can indicate a unified body. The following table describes some items that regularly get misrepresented and/or misspelt. More examples can be found at Common Errors in English Usage

fewer or less For "countable" things, use fewer. For things that are not "countable" - such as water - use less. See the BBC's Ten Questions on Grammar.
which or that "That" defines something, whereas "which" adds new information in a separate clause, often following a comma.  
who or whom To decide when to use "who" or "whom", ask yourself how the clause beginning with who/whom would read in the form of a sentence giving he, him, she, her, they or them instead: if the who/whom person turns into he/she/they, then "who" is right; if it becomes him/her/them, then it should be "whom". See:
UK Essays.com,
Improve Your Writing.


   

Click to reveal a QR Symbol for the Home Page