Content guidelines
A
Abbreviations and acronyms
In most cases, you should avoid abbreviations and acronyms unless they are widely used and easier to understand than the full text.
Spell out the word and put the acronym in brackets for its first use on each webpage. Consider providing a full explanation each time, because users may only read one section of your page and miss the full version.
Example: ‘The Department for Environment, Food and Rural Affairs (DEFRA) is the government department responsible for environmental protection.’
Do not use points or spaces. This includes proper names. Example: ‘mph, 4am, WH Smith’
Do not use Latin abbreviations such as ‘eg’ or ‘ie’ or ‘etc’. You should write out ‘for example’ and ‘that is’ in full.
It is helpful to add a brief description to provide context. For example: ‘the animal welfare charity RSPCA’.
When to use abbreviations and acronyms
It’s fine to use abbreviations and acronyms:
- if an acronym is better understood than the full text, then use the shorter form. Example: ‘GIF, MB, KB’
- if the individual letters are pronounced in the word, use all capitals. Example: ‘BBC, USA, CEO
- if the acronym has entered everyday language use all lowercase letters. Example: ‘radar, laser’
- if the short form version is said aloud as one word. Start with a capital letter. Example: ‘Nasa, Nato, Unicef’
Active voice
Use the active voice because it is clear, direct and helps to engage users.
Example: ‘The committee proposed the changes’ (active voice)
Not: ‘The changes were proposed by the committee’ (passive voice)
‘You can access the information on our website’ (active voice)
Not: ‘The information can be accessed by visiting our website’ (passive voice)
Ampersand
Always use ‘and’ instead of the ampersand sign ‘&’.
Some forms of screen reading software can’t recognise the ampersand symbol. It’s also a distractor, is taller than most letters and is an unusual shape. Some users will not understand what it means.
When to use the ampersand sign
It’s fine to use ampersands for:
- academic references. Example: ‘Brown, G & Smith, P’
- a company name as it appears on the Companies House register
- descriptions of logo images. Example: ‘M&S logo’
B
Bold, italics and underlining
Use bold sparingly. Using it too much will make it difficult for users to know which parts of your content they need to pay the most attention to. To emphasise words or phrases, you can use bullet points, headings or front-load sentences.
Do not use italics or underlining.
Bullet points
Use bullet points to split up long sentences and make text easier to read.
They should:
- complete a sentence
- be front-loaded with the most important information
- start with the same language element, like verb, noun, adjective
- be grammatically correct
- make sense running on from a lead-in line
- use lowercase at the start of the bullet
Do not:
- put a semicolon or comma at the end of a bullet
- put ‘or’ or ‘and’ after the bullets
- put a full stop after the last bullet point
C
Capital letters and sentence case
Do not capitalise whole words or phrases, they are harder to read. Use sentence case instead for headlines, subheadings and buttons because it’s easier to scan.
Do not capitalise terms, unless they are proper nouns. For example, you should write ‘we’re running a sustainability project’ not ‘we’re running a Sustainability Project’.
When to use capital letters
You can use capital letters for proper nouns.
It’s fine to capitalise the following:
- names of people, places and things, including buildings and brands
- specified committee, faculty, department, institute or school: ‘Equalities, Human Rights and Civil Justice Committee’
- names of groups, directorates and organisations: ‘Audit Advisory Board’
- titles of specific acts or bills: ‘Human Rights Act’
- names of specific schemes known to people: ‘Right to Buy’
- names of wars: ‘World War 1’ and ‘World War 2’
- job titles following the person’s name
- titles like ‘Mr, Ms, Dr, the Duchess of Cambridge’ (the duchess at second mention)
- titles of books
- header cells in tables: ‘Yearly budget’
Clear language
Plain English
Use plain English. Choose language that people understand and opt for easy, short words over formal, long ones. For example, choose ‘buy’ not ‘purchase’, ‘help’ not ‘assist’ and ‘about’ not ‘approximately’.
Try to keep sentences 25 words or fewer. The easiest way to do this is to keep it to one idea per sentence. Split long sentences up into 2 or 3, or use bullet points.
When you use a longer word (8 or 9 letters), users are more likely to skip shorter words (3, 4 or 5 letters) that follow it. So if you use longer, more complicated words, readers will skip more. Keep it simple.
Avoid using jargon. Jargon and clichés exclude people who speak English as a second language or anyone who has never heard the cliché.
Addressing the audience
Write conversationally, in first person. Picture your audience and write as if you were talking directly to them, with the authority of someone who can help and inform.
Use personal pronouns like ‘we’, ‘you’ and ‘us’. Use ‘we’ when referring to the Scottish Parliament, and address the user as ‘you’. This creates a cleaner sentence structure and more approachable content.
Example: ‘We offer education sessions online, and resources to help you learn about the Parliament. This section will help you understand who we are, what we do and how laws are made.’
Specialist terms
Create content that all users can understand, whatever their expertise or background.
If you need to include a technical or specialist term, explain it. Make sure the surrounding language is in plain English. To help users understand specialist terms, you could:
- link to an existing definition, this could be an external site
- add a explanatory definition after using the term
Legal, medical and financial terms
The legal, financial and medical fields are known for complex terminology which can be confusing for users. Use simple language for legal, financial and medical terms.
Explain the law in context. When you refer to a law, or part of it, explain what that law is at the point of user need. Do not only refer to it in a reference section or appendix.
Contractions
Simple positive contractions may be fine, such as ‘you’ll, we’ll, I’ll, there’s, they’re’.
Possessive nouns may be fine, such as ‘organisation’s, cat’s’.
Avoid negative contractions such as ‘shouldn’t, can’t, don’t’. Research shows many users find negative contractions difficult to read, and often misread them as the opposite.
Avoid conditional contractions, such as ‘should’ve, would’ve, could’ve’ as they’re harder for people with cognitive challenges to recognise and understand.
D
Dates and times
Do not use hyphens for time and date ranges, use ‘to’ instead. It is easier to scan, and a screen reader will read out the word ‘to’. If you use a hyphen or a dash, the screen reader will say ‘hyphen’ or ‘en dash’ or ‘minus’.
Example: ‘Monday to Friday’ or ‘10am to 11am’
Dates
Put the date in numerals and spell out the month in words, followed by the year in numerals. Do not use ‘st’ or ‘th’ for dates, and avoid putting commas in between.
Example: ‘18 July 2019’
If space is an issue, such as for tables or publication titles, you can use truncated months. Example: ‘Jan, Feb’
Times
Use the 12-hour clock followed by ‘am’ or ‘pm’ without a space.
Here are some examples:
- ‘5:30pm’ not ‘1730hrs’
- ‘midnight’ not ‘00:00’
- ‘midday’ not ‘12 noon, noon or 12pm’
- ‘6 hours 30 minutes’
H
Headings and titles
Use clear, concise, front-loaded headings that are specific and descriptive. Write in sentence case. Example: ‘Gender-recognition reform: committee launches consultation’ not ‘Holyrood Committee Launches Consultation On Gender Recognition Reform’.
Make sure headings are meaningful and not generic so that users can scan the page easily.
Statements work better than questions in headings. They enable you to put the keyword first. Example: ‘Canteen menu’ not ‘What’s on the menu at the canteen today?’
Title of content
This is what people will see in the search results. Be clear, concise and to the point. Action-orientated headings work well. Avoid using puns, idioms and colloquialisms as these can be hard to decipher for those with English as a second language or reading challenges. Example: ‘Book a guided tour’.
Structure your page with headings. Think about what your user needs, and structure those needs into headings on the page to indicate importance or process.
Hyperlinks
Use sentence case for hyperlinks, buttons and call to action links. You should:
- always make sure that link text is meaningful so people with screen readers can navigate easily. It should match the destination, so it's clear to the user where the link will take them.
- never use generic phrases like ‘find out more’ or ‘click here’. Generic links do not make sense out of context or tell users where a link will take them. They also do not work for people using screen readers, who often scan through a list of links to navigate a page. It’s important the links are descriptive so they make sense in isolation.
- front-load your links by putting keywords at the beginning. Example: ‘Buy yellow shoes’.
- avoid mid-sentence links. They can be distracting, slow down users and they may cause readability challenges for autistic users. For example, use ‘Learn more about this project by reading the Readability Guidelines blog posts’ and not ‘Learn more by reading the Readability Guidelines blog posts about this project.’
Opening links in a new tab or window
Avoid opening links in a new tab or window. It can be disorienting, and can cause accessibility problems for people who cannot visually perceive that the new tab or window has opened.
There are some occasions where it may be appropriate to open links in a new tab or window, such as opening help instructions which are needed to complete a task, or completing a form where the user will rely on information on the source page.
If you decide to open a link in a new tab or window, provide an advance warning in the hyperlink text.
Read W3C guidance on opening new windows and tabs.
Calls to action and buttons
Start call to action (CTA) links and button text with a verb. Example: ‘Book your ticket’
Make the text specific so users know where the button or CTA will take them.
Calls to action should be direct and use active language. They are there to signpost or encourage the user to take the next step. Aim for link text to make sense in isolation without reading words around it.
Make CTA links and button text 2 to 4 words so that they are quick to absorb. Concise CTA text allows users to make an instant decision on whether or not to click. Example: ‘Shop now’
Sometimes you may need to make them a little longer so that you can include all the words of the thing someone is applying for. Example: ‘Apply for an older person's bus pass’
Icons
We have several icons available for particular types of link content. These can be used to give links more prominence. For this reason, they should be used sparingly and always on a separate line.
This link is used for parliament guidance materials
This is a link to a PDF (4MB, pdf) posted 29 July 2022
Previously, we asked editors to use the 'external link' icon when linking to an external or third-party website:
This is a link to a third-party website
However, user research indicates that the purpose of this icon is not widely understood, and it is not implemented consistently. On that basis, when you need to give a link to a web page more prominence you should use the 'arrow' icon, even when linking to non-parliament websites.
Hyphens and dashes
Use hyphens and dashes sparingly. Hyphens slow online comprehension, and take longer to scan. They can cause readability issues.
If you are using hyphens, make sure your hyphen usage is up to date. Hyphens often disappear when words become more common (‘inter-net’ became ‘internet’, ‘de-regulate’ became ‘deregulate’).
Be consistent with your hyphen choices (for example if you choose to use ‘full-time’).
Avoid using dashes wherever possible. Replace dashes with commas if you can. Screen readers don’t read out commas, but they do say ‘hyphen’ or ‘en dash’ for every time you use those types of punctuation. If you do use a dash, use an en-dash instead of a hyphen or em-dash.
When to use hyphens
It’s fine to use a hyphen:
- if the word or sentence is confusing without it. Consider rewriting the sentence to remove the hyphen. For example ‘this cereal has no sugar’ instead of ‘this cereal is sugar-free’, or ‘250-year-old trees’ could be ‘trees that are 250 years old’
- when a word has a different meaning without it, for example ‘re-cover’ and ‘recover’ or ‘co-op’ and ‘coop’
I
Images and infographics
If you can get the message across by just using words, then it’s best to do so. If you are using imagery (pictures, graphs or charts) then think about how you’ll make the content accessible for people with a visual impairment. You should also avoid images containing text, as it’s usually not possible to resize the text in the image without it becoming blurry.
If you decide to present content as images or infographics, make sure it is inclusively designed:
- images: use alt text if the image contains useful information
- infographics: provide a text version of the infographic
Alternative text
Every image should contain an alternative text description, also known as alt text. Write a succinct description of what you can see. You don’t need to write ‘image of’ of ‘picture of’.
Think about the information contained in the picture, and create a mental image of it for the user. If an image is purely decorative, you can write ‘null’.
Inclusive language
Use respectful terms for disability, mental health and dying. Use positive, enabling language. Do not present people who deal with physical, mental and emotional challenges as victims.
The word ‘disabled’ is a description not a group of people. Use ‘disabled people’ not ‘the disabled’ as the collective term.
Use the terms ‘inclusive’ or ‘accessible’ for things designed to provide an equal experience.
Avoid referencing the following unless it’s absolutely relevant:
- gender
- age (if you have to, use ‘younger people’ and ‘older people’)
- medical, mental or cognitive conditions
- heritage and nationality
From GOV.UK:
N
Numbers
Use numerals instead of words for numbers. They are easier to scan-read. Example: ‘You’ll be shown 14 clips’
Don't use roman numerals. Screen readers will read them out as letters.
Use percentages and the percentage symbol ‘%’. Example: ‘50%’
Be specific with data, for example ‘20 people’ not ‘20% of survey group’.
Use a space between a number and a unit of measurement. Example: ‘5 KB’ or 10 km. (The only exceptions to this rule are for the unit symbols for degree, minute, and second for a plane angle.)
Use 2 decimal places. Example: ‘4.03 MB’
Use ‘to’ for number ranges, not a hyphen. Example: ‘500 to 900’ not ‘500-900’. Also bear this in mind for address ranges, for example ‘49 to 53 Cherry Street’.
Use years and months not just months, it is more comprehensible. So use ‘1 year 6 months’ and not ‘18 months’, ‘a year and a half, or ‘1.5 years’. If it is below 1 year, use ‘x months’.
Q
Quotation marks
Use double quotation marks for speech and quotes. Example: “I am going to walk the dog today,” he said.
Use single quotation marks for a quote within a quote. Example: “She said to me, ‘This will never work.’”
V
Video
Video content and moving images are less accessible than content presented as text. As well as causing access barriers, adding cognitive load, and distracting from other content they can cause serious harm to motion-sensitive users. Ask if you really need video content or moving images to communicate your message.
Making video content accessible
If you choose to use video, make it the main feature of the page. This is because it can be distracting and make it harder for users to focus on other content on the page. Put important information which is not part of the video on a different page. Aim to keep video content simple.
Do not autoplay videos. This causes usability issues for users. The Web Content Accessibility Guidelines say you must include controls to stop, pause and hide the video if it does autoplay.
Never include flashing images and avoid other content that could be harmful for users. Flashing images, or apparently flashing images, like fireworks or gunfire simulation, could trigger a photoepileptic seizure. Avoid completely.
Transcripts and captions
Always provide the video content in a text format such as captions and transcripts. Transcripts and captions need to be readable, so follow all the readability guidelines. For example, do not present them in block capital letters. And make sure your transcripts are accessible for screen reading and text to speech software.
You should also:
- consider including sign-language translation in your video
- consider providing audio descriptions of what is happening in the video, the soundtrack may not communicate everything