|General Writing Tips|
[Last updated: 24-Mar-2021]
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.
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.
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
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|
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.
|Image Type||Best used for...|
|.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
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:
|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,
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.
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
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
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:
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 (,)!||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,
"...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 (*)) 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
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
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
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, 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
||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 numberical digits; write the number
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 = 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:
|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 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
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; 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
|When to Use||Description||Reference/Justification|
|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.
This section contains a list of useful web pages (opening in a new tab) that can be used to produce high-quality documents.
|Subject||Reference Web Page|
|Acronyms and Abbreviations||http://www.acronymfinder.com|
|BBC News Style Guide||https://www.bbc.co.uk/academy/en/collections/news-style-guide|
|BBC News Style Guide (Searchable Version)||https://www.bbc.co.uk/academy/en/articles/art20131010112740749|
|BBC News Style on Grammar (by Ian Jolly)||https://www.bbc.co.uk/blogs/collegeofjournalism/entries/ca8cdc25-aaf5-3bc4-8125-520ab18a68bf|
|Bureau International des Poids et Mesures (English Version)||http://www.bipm.org/en/si/si_brochure/|
|Cambridge University Press||http://dictionary.cambridge.org|
|Common Errors in English||https://brians.wsu.edu/common-errors/|
|Creating an MS Word Template||http://word.mvps.org/FAQs/Customization/CreateATemplatePart2.htm|
|(The) Free Dictionary||https://www.thefreedictionary.com/|
|French Guillemet Quotation Marks||https://www.thefreedictionary.com/Guillemets|
|Google Style Guide||https://developers.google.com/style/|
|History of Sentence Spacing||https://en.wikipedia.org/wiki/History_of_sentence_spacing#French_and_English_spacing|
|Ian Jolly is Style Editor||https://www.bbc.co.uk/blogs/collegeofjournalism/authors/552e4436-4ff5-385a-aa1c-973b4427bf25|
|International System of Units||https://en.wikipedia.org/wiki/International_System_of_Units#SI_writing_style|
|Larousse Dictionary and Translator||https://www.larousse.fr/dictionnaires/bilingues|
|MacWord's Normal Template||https://wordmvp.com/Mac/MacWordNormal.html
Note: Although written for the Mac version of Microsoft Word, a lot of the topic applies to the Windows version.
|Microsoft Word Add-Ins||https://wordaddins.com/|
|Microsoft Word Templates||https://docs.microsoft.com/en-us/previous-versions/office/developer/office-xp/aa140287(v=office.10)|
|Oxford Advanced Learner's Dictionary (OALD)||https://en.wikipedia.org/wiki/Oxford_Advanced_Learner's_Dictionary|
|Oxford Learner's Dictionaries||https://www.oxfordlearnersdictionaries.com/|
|Reuters Style Guide||http://handbook.reuters.com/?title=The_Reuters_Style_Guide|
|[The Late] Shauna Kelly||https://shaunakelly.com/word/index.html|
|[The Late] Shauna Kelly Bullets||https://shaunakelly.com/word/bullets/controlbullets.html|
|[The Late] Shauna Kelly Basic Concepts||https://shaunakelly.com/topic/word/concepts.html|
|[The Late] Shauna Kelly Control Bullets||https://shaunakelly.com/word/bullets/controlbullets.html|
|[The Late] Shauna Kelly Templates||https://shaunakelly.com/word/templates/templaterelations.html|
|Space (Normal Puncuation)||https://en.wikipedia.org/wiki/Space_(punctuation)|
|Telegraph Style Book||https://www.telegraph.co.uk/style-book/|
| || |