Style and writing guide
Writing basics
Guidance on simple and clear writing.
Everything we write should be simple and clear to ensure that our services are accessible to as many people as possible.
To do this we write in plain English and there are a number of basic techniques you can apply. These are:
- try to avoid words with 3 syllables or more
- use short sentences (25 words max)
- try to limit paragraphs to 3 sentences
Key points when writing
- understand who your audience or user is and write for them directly
- make the meaning clear and avoid using jargon
- don’t use underlining, italics or BLOCK CAPITALS to emphasise content, use defined headings tags instead
Active and passive voice
Use active voice not passive voice. Active sentences are more direct and make it clear who’s responsible for what.
Read the Cambridge Dictionary entry for more guidance on active and passive voice.
Examples
Active voice: You can apply if you used to live in Scotland.
Passive voice: Applications can be made by people who have previously lived in Scotland.
American and UK English
Follow the GOV.UK style guide entry for ‘American and UK English’.
Email addresses
Links and URLs
Web content
Front-load your link text with the relevant terms.
Make your link text descriptive. It's important that users can understand where the link goes even if it's read out of context with the text around it. This happens when someone is using screen-reading software.
Always link to online services first.
Offer offline alternatives afterwards, when possible.
Do not:
- use generic terms like ‘click here’ as link text
- use links in titles, subheadings or summaries
- duplicate content available elsewhere across the site, link to it instead
- use the same link text to link to different places
- use unsorted lists of links at the bottom of the page to point users to content you think they might be interested in
Follow GOV.UK guidance about using links in web content, including:
- providing links in context
- writing link text
- anchor links
- formatting links
- linking to attachments and documents on other websites
Emails
Follow Gov.UK Notify guidance on links in emails.
Offline content
Do not add a full stop at the end of a link in offline content, including letters, forms and text messages.
A full stop at the end of a link in offline content could break a user journey if the user adds the full stop in the web browser.
Text messages are considered offline content because not all users have a smart phone.
Text messages
Follow Gov.UK Notify guidance on links in text messages.
Letters and forms
Do not add a prefix to URLs in letters and forms.
Use: mygov.scot/example
Do not use: https://www.mygov.scot/example
Lists and steps
Make all lists as short as possible. Break up long processes using separate headings containing separate lists.
Bullet points
Use bullet points for a list that’s not sequential steps.
Bullets:
- follow on from an introductory sentence
- have an introductory sentence ending with a colon
Do not:
- use more than one sentence per point
- begin any point with a capital letter, unless it’s a proper noun
- end any bullet point with a full stop
Numbered lists, or steps
Use numbered lists for actions the user needs to take in a certain order. Write numbered lists:
- as a full sentence
- with a capital letter at the start of each point
- with a full stop at the end of each point
Restart from 1 in each heading.
Nested lists
Use headings to break up long lists.
Only use a nested list if it’s the simplest way to present the information.
Do not nest a list of numbered steps if the main list is bullet points.
Example
Use this guidance to process complete applications for:
- Carer Support Payment
- disability benefits:
- Adult Disability Payment
- Child Disability Payment
Submit the application
- Ask the client to sign the completed application.
- Attach it to their record.
Assign a task
- Create a task:
- Select 'Create task'.
- Enter the application ID number in the 'Description' box.
- Assign the task to either a:
- team support officer
- team leader
Please
Avoid using but can be judged case by case.
Sentence length
Make your average sentence 15 words long. 15-word sentences are more likely to be understood.
The maximum sentence length for a good level of comprehension is 25 words. Split longer sentences up into 2 or 3, or use bullet points. Sentences above 40 words are hard to comprehend.