General Writing Tips

[Last updated: 01-Jul-2022]

Based on my professional experience with documentation, this page started out as, and continues to be, a list of tips when producing documents. The art of handwriting is another topic, and is covered by the Handwriting page.

* * *

This page describes a number of topics on how to maintain consistency when writing documents. The subject matter came about during a specific time when I was working for GlaxoSmithKline in Belgium. Most of the documentation was written in English by authors whose mother tongue was French and/or Flemish. I was required to review the documentation, following some negative feedback from a non-English speaking country, about the quality of the written text.

There is one exception to this, namely Favicons. It is here (for the time being) simply because I didn't know where else to put it.

General Writing Styles

Tables/Lists following a Heading - It is not good practice to start a section directly with a table/list, as it is wrong to assume that the reader knows what the contents of the table/list is about or represents! It is best practice to precede a table/list with an introductory description, or an explanation about what is to follow; for example, "the following table contains..." or "the following list illustrates...".

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(s) 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 because of 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, the word must can be audited. Thus it is permitted in a Policy or Standard Operating Procedure.

However, the word is not permitted in a guideline document or work instruction. 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

When applying illustrations, 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 limit on the size of e-mail messages. Images come in many different formats: Portable Network Graphics (PNG), 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.

.png The Portable Network Graphics format supports up to 16 million colours. 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.
.jpeg The Joint Photographic Experts Group format supports up to 16 million colours. 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. If a large number (of raw images) is inserted into a document (for illustration purposes), the final physical size of the document could be dramatically increased. The end result could result in the document being too large to send through a company's e-mail application; some, of which, have a limitation of 20 MB. Therefore, to avoid this scenario, consider using an image editor to reduce the size of the image(s); and ultimately the overall size of the document.
.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 (for example, Microsoft Outlook), the e-mail application could fail to send it, because the message is too large. Some companies apply a maximum size (for example, 20 MB) to all out-going messages.

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), and re-inserting the smaller .jpg images back into the document, the document was reduced to under 20 Mb. The resulting message and its attachment was then small enough to be sent through the company's e-mail application, as it was under the company's 20 Mb limit!
.vsd Visio drawings. This format is ideal for producing flowcharts. To transpose a copy of the image from Visio into a document, either:
  • Create a group of the required shapes
  • Copy the complete group
  • Paste the group into the destination document.
  • Create a group of the required shapes
  • Export (Save as...) the complete group as an external image (for example, .png)
  • Insert the image into the destination document.
The latter process is particularly favourable if the image is to be used in several different documents.
Capturing (Parts of) a Window The Windows operating system has a capturing tool called "Snipping Tool". Use this to capture any part of a screen and save the result as a .png file.

However, if this tools is not available, the contents of the whole screen can be captured by pressing the <Print Scrn> key. To capture a specific window, select the window and press <Alt> + <Print Scrn>. Then paste the captured image into the destination document.

Note: If using either of the <Print Scrn> key combinations, avoid pasting the captured content directly into a document, as the resulting format is uncompressed; it has the Bitmap format. If there are multiple illustrations to capture (using <Print Scrn>), the receiving document could end up being extremely large! This can present difficulties with disk and e-mail quotas, as described above! Instead, use an image editor (MS Picture Manager or Paint Shop Pro), Export (Save as...) the image as a .png or .jpg file, and Insert the saved image into the destination document.
Instructions, Notes and References Do not place notes, instructions or references on an image. These items must be located within the document text.

Reason: 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 a long time later, it is possible that the original image file is no longer available!
Scaling When illustrating a series of images, it is recommended that they are all resized to the same scale, keeping them all relatively proportioned to each other (as in real life); for example, reduce all pasted images to 50%. Thus, a simple pop-up ‘Yes/No’ confirmation button or 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.


Although not a writing tip as such, a favicon, or Favourite Icon, is a small web-based image file that is associated with a particular web page or website.

Some on-line references (such as Wikipedia) state that a favicon file (with a .iso extension) should reside in the root directory of a web site. That is not strickly true.

Following a successful trial on this web site, I create small square .png image files (of either 32x32 or 64x64 pixels). Why? Because they are easy to edit. Once created, I place them in a dedicated directory containing all favicons on this site. Where active, a line of code in the <head> part of the HTML file, contains a reference to the required favicon file.


Where possible, include flowcharts throughout the document; and if it is a procedure, a flowchart is important to illustrate the process.

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.
Do not place abbreviations in headings. Not everyone knows or understands what the abbreviation represents.
Plural abbreviations do not contain apostophes; i.e., Business Instructiuons (BIs) and Standard Operating Procedures (SOPs).

Note: 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 (British Telecommunications) and
GSK (GlaxoSmithKline).

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 (Acquired Immune Deficiency Syndrome).
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 example 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 (,)! When writing, think about your audience! If it 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 to Keys

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 and to emphasise the actual keys that need to be pressed.
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, " 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 (*)) that 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 several ways, depending upon where you are in the world:

dd-mm-yy - 04-May-2006
mm-dd-yy - 05-Apr-2006
yy-mm-dd - 06-May-2004
yy-dd-mm - 05-Jun-2004
To ensure clarity and consistency, it is safer to 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!
Filenames Keep filenames as short as possible. Filenames should never be stories! The purpose, or a full description of the document, must appear in the first section/chapter of the document.
Version Numbers If used, NEVER quote document version numbers [unless there is a specific reason; for example, to refer to some deleted text]!

Reason: If version 04 of a document is used, and that version has been updated and released as version 05, version 04 immeditely becomes out-of-date!
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 a 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, consider splitting the flowchart across 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, as 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 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 (Fr: vingt personnes étranges)
  • Twenty-odd people (Fr: 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, items, figures, etc., especially when they are written or printed. [Oxford Learner's Dictionaries] 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.
  • Correct: Krono has three lines of business. It manufactures chemicals, paint and pharmaceuticals.
  • Correct: 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 numberical digits; write the number in full.

Note: Unit symbols are unchanged in the plural form; for example: 25 kg, not 25 kgs; see the SI Writing Style.

To prevent a number from being separated from its unit at the end of a line, use a non-breaking space (HTML code = &nbsp; or Word = <Ctrl> + <Shift> + <Space>) between the last digit and its unit; for example: 25 cm.
Pronouns There is a distinct lack of pronouns (I, you, etc.) now-a-days, making some text confusing and ambiguous.
What on earth does the following American statement mean:
In either case, would like to confirm that these docs are OK to release for approval.
The first possibilty could be a question (without a question mark!), while the second could be a statement:

In either case, would you like to confirm that these docs are OK to release for approval
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:
Spaces (in Microsoft Word) 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


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; see Captions - in Word Tips). 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

fewer or less For "countable" things, use fewer.
For things that are not "countable", such as liquids, 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. "Which" follows a comma, whereas "that" doesn't.
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.

Other Reference Pages

This section contains a list of useful web pages (opening in a new tab) that can be used to produce high-quality documents.

Acronyms and Abbreviations
BBC Americanisms
BBC News Style Guide
BBC News Style Guide (Searchable Version)
BBC News Style on Grammar (by Ian Jolly)
Bureau International des Poids et Mesures (English Version)
Cambridge University Press
Collins Dictionary
Common Errors in English
Creating an MS Word Template
(The) Free Dictionary
French Guillemet Quotation Marks
(The) Guardian
Google Translator
Google Style Guide
History of Sentence Spacing
Ian Jolly is Style Editor
International System of Units
Larousse Dictionary and Translator
Lorem Ipsum
MacWord's Normal Template

Note: Although written for the Mac version of Microsoft Word, a lot of the topic applies to the Windows version.
Microsoft Word Add-Ins
Microsoft Word Templates
Oxford Advanced Learner's Dictionary (OALD)'s_Dictionary
Oxford Languages
Oxford Learner's Dictionaries
Reuters Style Guide
[The Late] Shauna Kelly
[The Late] Shauna Kelly Bullets
[The Late] Shauna Kelly Basic Concepts
[The Late] Shauna Kelly Control Bullets
[The Late] Shauna Kelly Templates
Space (Non-breaking)
Space (Normal Puncuation)
Telegraph Style Book


Click to reveal a QR Symbol for the Home Page