[Last updated: 11-May-2018]
This page describes a number of topics on how to maintain consistency when writing documents.
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.
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|
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.
|Image Type||Best used for...|
|.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
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
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
|Capturing (Parts of) a Window||To capture the contents of the whole screen, press
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,
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:
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:
|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
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,
|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
|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
rather than a Table of Contents (TOC), or even the the first
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:
|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:
||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
||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.
|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
|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:
|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:
|References to Keys||When writing references to keys of the keyboard, or parts of a
screen display, ensure that the reference text:
||This avoids confusion from normal text; for example:
|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
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:
|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
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.|
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
|When to Use||Description||Reference/Justification|
|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:
Improve Your Writing.
| || |