This covers grammar and formatting for our content.
We also have a list of standard terms – to keep language consistent across all platforms and projects.
These rules follow the guidelines from the Plain English Campaign and the Government Digital Services style guide. They are also based on readability and accessibility tests.
If you'd like to know more about how this guide was put together, or have questions about writing for Smart, please get in touch with one of the Content Designers.
Write the first instance out in full, with the abbreviation in brackets. Then use the abbreviation for all other instances on the page.
Examples:
Abbreviations, such as Doctor (Dr), or London Drive (London Dr).
Acronyms such as for your information (FYI).
Initialisms, such as Her Majesty's Revenue and Customs (HMRC).
This is an accessibility guideline, meeting Success Criterion 3.1.4 Abbreviations, level AAA.
We use active voice most of the time. This is where the agent, or 'doer', comes before the verb. For example:
Sometimes, the passive voice can make your content read more naturally, so there's no need to avoid it every time. It can also be used in error messages caused by user error, as it's less accusatory. For example, "your password was entered incorrectly" is in the passive voice, but it's friendlier and less accusatory than "you entered an incorrect password".
A good rule of thumb to help you identify passive voice is to add the phrase "by monkeys" to the end of your clause ("Your account will be closed... by monkeys"). If it still makes sense, you're probably writing in the passive voice.
We format addresses and label data entry fields as follows
Address line 1
Address line 2
Town
County (optional)
Postcode
We don't use them, unless they're part of a brand name, like Legal & General.
If you're replying to a tricky letter or a complaint, or are dealing with a difficult problem, put yourself in the reader's shoes. Be professional, not emotional.
You may have to give a firm, unwelcome answer, but be as helpful and polite as possible. If you are going to apologise, do so early. If the problem is your fault, say so.
Apologise completely and concisely, sympathetically and sincerely. And whether it is your fault or not, try to emphasise what you can do for the other person.
With content that’s audio-only, like podcasts and voice-only presentations, we need to include a link to the transcript of the recording.
This is an accessibility requirement, meeting Success Criterion 1.2.1 Audio-only and Video-only (Prerecorded), level A.
"Back" and not "Previous" or "Go back".
Use to indicate actions/buttons in instructional content. For example, "press Continue".
You can also use bold sparingly to emphasise important information.
Stick to British English – avoid Americanisms.
You can use bullet points to make text easier to read.
There are two ways to format bullet points. Avoid switching between these two ways of formatting within one page or document.
Short list bullets
When you're listing short information, you can use a bulleted list like this. Make sure that:
Full sentence bullets
This in an alternative way of formatting bullets, for when you're listing longer points.
Buttons should be simple and direct "Start now", "Continue" and "Back" are the standard buttons for our transactional user journeys.
More specific button text should be used when you're asking a user to complete a single action. Customise this text to describe the action as accurately as possible. The resulting label should complete the sentence “I want to…” from the user’s perspective.
People find capital letters harder to read. Always use sentence case – even for titles and headings – except when using brand or product names (for example, "Smart Pension", "Legal & General", "MacBook Pro").
Don't use title case in URLs (smartpension.co.uk, not SmartPension.co.uk). The only exception to this is when you're referring to the Smart Pension Master Trust – as this is the official name of the trust.
It's not commonplace to use capital letters in email addresses, and we don't do it.
We avoid writing anything in all caps, as it's not accessible and doesn't fit in with our tone of voice.
Only use to introduce bulleted lists, or to introduce examples which include numbers.
A good rule of thumb is – if you want to use a colon, use a dash instead.
We don't use Oxford commas, also known as serial commas. An Oxford comma is when you use a comma in a list before the word "and".
For example, it should be: "I went to the beach with my dog, Auntie Jill and David". Not "I went to the beach with my dog, Auntie Jill, and David".
You can use a comma before "and" if the context isn't a list, and it will introduce a new clause or break up a long sentence.
A conjunction is a "joining word", that links different parts of a sentence together – such as "and" or "but". And they can be used to start sentences.
Should say "Continue" rather than "Next" or "Proceed".
Use "Continue" where it's not necessary to explain to the user exactly what the button does. For example, if the button submits the information they've entered and takes them to the next step in an application, "Continue" is better than "Submit details and continue".
A contraction is a shortened version of two words, written as one word. Often, they use apostrophes to signify missing letters ("didn't", "can't", "shouldn't")
Use these to make your content informal and friendly, but don't overdo it. Too many contractions can make content hard to read.
Dashes work well when used in place of colons. Use en dashes (–), not em dashes (—). A hyphen doesn't count as a dash – it's a hyphen.
On a Mac, type an en dash by selecting the Option + Minus keys at the same time.
Don't use dashes in lists or tables of numbers or financial information, as they can look like a minus sign.
Don't use these – use "For example," instead.
Use "Edit" and not "Change" or "Amend".
Should be all lower case for readability. For example:
We use two types of error messages – alerts (boxes that pop up out of the form or page) and inline errors (error messages that appear by the incorrectly filled form field).
Alerts
Alerts should lead in with a simple statement of fact, followed by a broad description of the options available on the page. For example, "It looks like your income could run out when you're 78.”
If you want your income to last longer, you could lower your monthly income or move more money into this pot".
Avoid stating whether an alert is positive or negative. In the example above, it would be wrong to say "There's a problem - your money might run out when you're 78. To fix this, (...)" – as it's impossible to know the user's future plans or overall financial situation.
Inline errors
Unlike regular error messages/alerts, inline error messages don't necessarily need to explain what went wrong. Telling the user the solution is often enough to prompt them to correct the error, especially in simple forms. For example, "Please enter your name" is enough to prompt a user to fill in a form field they accidentally missed.
Explaining the error can make the message unnecessarily long and harder to read. For example, "You didn't enter your name. Please enter your name" is overkill for a simple to understand and easy to fix error.
Don't use it. If you find yourself in a situation that calls for the use of something like this use "and more" instead.
Use them sparingly – they may be useful in specific cases (such as celebration moments) when there is less need to be formal!
Use "Quit". Can be more specific, like "Quit transaction".
We have a "no-FAQs" rule. Our existing content and products should be written and structured in a way that the user does not have to ask questions in order to find out what they need to know or complete a task.
If there is no other solution than to use a question as a subheading, write the question in the first person.
Use upper-case when referring to file extensions in body copy. For example, "PDF" and not "pdf".
If a link opens a file, then tell the user by specifying the file extension in brackets after the CTA copy. Use lower-case and a stop before the file extension. For example, "Download statement (.pdf)".
Two words, no hyphen. Use "first name" rather than "forename", etc. Only capitalise if at the beginning of a sentence.
You should follow the VID (Visual Identity) design guidelines on which fonts to use and how to present them.
Use normally in sentences and paragraphs. Don't use them to end headers.
The exception to this is error messages, which should have a full stop at the end of the header. If there are two sentences to the error message, use to end the first sentence.
Where there is a sentence that ends with something in quote marks, the full stop should go "outside the quotation marks like this". It's the other way around for US English.
Don't use full stops:
We never ask a user for their sex or gender unless it is absolutely essential. If we do have to ask for it, we must tell them why we need the information.
The main case for asking for a user's gender is when we have to ask a member for their legally recognised gender. This is because it is a requirement from the government on any RTI (real time information) data that's submitted to do with PAYE. More information can be found here on the government website.
Where we must ask for the member's gender for this reason, we say:
"Select your legally recognised gender. HMRC uses this for tax services."
Or, if the information was already supplied by their employer:
"Your employer told us your legally recognised gender when you joined Smart Pension. HMRC uses this for tax services."
All external emails should start with "Hi [first name]" and end with "The Smart Pension Team" (or whatever team is most appropriate)
All page titles, headings and subheadings should be written in sentence case (not Title Case).
Use a heading that is specific enough to tell the user exactly what the page or form field does. For example, "Reset your password" not “I don’t know my password”.
People reading just the header, subheader, label or page title should know what to expect.
If the page is part of a collection of pages, we should also make that clear from the title.
Where there is only one action a user can take in a section, use the format "[Verb] the [noun]" or "[Verb] your [noun]".
Where a user can take multiple actions on a page, or for section headers and landing page headers, use a noun that covers all of the actions where possible. For example, "Contributions".
For platform content, we do not use questions as subheadings. Where it is completely unavoidable we use the first person for questions.
Text content should be organised with headings, wherever possible, to make it easier to navigate. For example in long form content, information articles and content that can be organised, like a ‘Setting’ menus.
Some bits of content, like long letters, may not be suitable.
We should also use headings in the right way if we have control over them. For example, if there are sub-topics, we should use H3s under the relevant H2 and so on.
This is an accessibility requirement, meeting Success Criterions 2.4.2 Page Titled, level A, 2.4.6 Headings and Labels, level AA, and 2.4.10 Section Headings, level AAA.
Use when creating compound adjectives. For example, "long-term investment".
When you're using content like images, charts, graphs, or thumbnails, these need to have text alternatives.
For simpler content, like images or thumbnails, you must write a short caption that describes what it is. You must also use the alt text feature of the content management system (CMS) you’re using, This should be a descriptive sentence explaining the information conveyed in the image as the alt text. Alt text is what appears on a page if the content does not load. It is also what screen readers read.
For example, your caption could be ‘Andrew Evans and Will Wynne opening the Smart Building office’. Your alt text could be ‘Andrew Evans and Will Wynne surrounded by Smart colleagues on the ground floor celebrating the opening of the new Smart Building office’.
With content that’s more complicated, like graphs or diagrams, it’s not possible to give the same experience with just a short description. There needs to be more information.
There must be both a short description and a long description. The aim is to create the same experience with your text as you get from the content.
The long description should be on the same page, and close to the content it is detailing.
For example, a graph showing Smart’s growth could say “This graph shows Smart’s growth”.
The long description could say ‘This graph shows that since 2019 Smart has grown almost 2,000%, with growth accelerating. In 2019 growth was 200%, 2020 growth was 250% and growth in 2021 was 330%’.
This is an accessibility requirement, meeting Success Criterion 1.1.1 Non-text Content, level A.
Two words, no hyphen. Use "last name" rather than "surname". Only capitalise if at the beginning of a sentence.
Use the phrase "learn more" rather than "find out more" or anything else. "Learn more" should usually be followed by "about...". For example, "Learn more about tax".
Links should be followed by a full stop if they appear at the end of a full sentence, but the full stop should be outside of the link.
If the link appears in isolation, no full stop is necessary.
Links are used for navigating to a new page or going to an external page or document.
You should use buttons where the action causes a change to a page, for example submitting a form or opening a pop-up or panel on a page.
Use links in body text, but not in titles, summaries or subheadings. Use a full stop after a link if the link ends a sentence. For links that lead a user to a screen where they can start an action, start your link with a verb.
For links that lead to an information page, put the link in context. You can do this by using the title of the destination page. If the page title does not give context, describe where the link goes.
Tell the user if you’re linking to an external website. For example, "Pension Wise has more information on the lifetime allowance”. Generally avoid using generic links like "Click here”. Generic links don’t make sense out of context and don’t tell a user where the link will take them. Remember, one word links can be hard for users with reduced mobility to use.
Links should be followed by a full stop if they appear at the end of a full sentence, but the full stop should be outside of the link.
If the link appears in isolation, no full stop is necessary.
This is an accessibility requirement, meeting Success Criterion 2.4.4 Link Purpose (In Context), level A.
A nominalisation is where you turn a verb (process, technique, emotion) into an abstract noun.
For example:
Like passive verbs, too many of them make writing very dull and heavy-going. Avoid them.
Sentence case – not Participation Agreement.
Avoid the passive voice – it's wordy, difficult to follow, and often alienates us from our reader.
You can easily move most instances into the active voice.
A good rule of thumb to help you identify passive voice is to add the phrase "by monkeys" to the end of your clause ("Your account will be closed... by monkeys"). If it still makes sense, you're probably writing in the passive voice.
Find more details on the passive voice and how to spot and avoid it on the Smart names page.
Always style with upper case P and S, including in the acronym (as above).
We want to make sure we're always being inclusive when talking to or about our users. This means using appropriate pronouns.
When talking to a user always use second-person pronouns. When talking about Smart always use first person pronouns. For example, "We'll send you an email".
When talking about a user, always use they/them pronouns unless you know their pronouns.
Never address anyone by or refer to anyone by she/he pronouns unless you definitely know which ones they use.
Use single quotes when paraphrasing something. Use double quotes in all other instances.
Where there is a sentence that ends with something in quote marks, the full stop should go "outside the quotation marks, like this". For US English, it's the other way round and the full stop should go "inside the quotation marks, like this."
Don't use them. Ever.
You can capitalise the words "team", "practice" or "discipline" if it forms part of a name. For example, Team Awesome, the Design Practice, or the Marketing Team.
You shouldn't capitalise it if it doesn't form part of a name. For example:
We capitalise PEG names as though they are proper nouns. For example, the Savings and Administration PEG. Or the Retirement and Member Payments (RAMP) PEG.
For any online content (on the platforms, in emails, on websites), avoid URLs – link with some descriptive anchor text (Read about the annual allowance on the Pension Wise website, not www.pensionwise.gov.uk). The exception to this is PDFs, where you need to write the URL out.
When you do need to write a URL out, always use www. at the beginning. Don't use title case in URLs (www.smartpension.co.uk, not www.SmartPension.co.uk), as this makes them harder to read.
Whenever we hyperlink text, there must be a description of what the link is or where it goes. The simplest way to do this is to describe the purpose of the link in the hyperlinked text or using the page title. We can also use icons (pdf icon describes the type of document), and alt text.
For example, visit our support site to find out how to sign in on our How do I sign in article.
On the platform, we will use aria tags, due to space limitations.
This is an accessibility guideline, meeting Success Criterion 2.4.9 Link Purpose (Link Only), level AAA.
Unusual words and difficult words, including idioms and jargon, need to have definitions, so users know what they mean. An unusual word is one that’s not used in everyday conversation,
The first time an unusual word or phrase is used we should write an inline definition.
If the word or phrase has multiple meanings in the same page, then we should write an inline definition each time there is a new meaning.
This is an accessibility guideline, meeting Success Criterion 3.1.3 Unusual Words, level AAA.
For video-only content, like silent movies, silent demos and animations, there needs to be a text description that describes what’s happening on screen.
The aim is to create the same experience with your text as you get from the video.
This is an accessibility requirement, meeting Success Criterion 1.2.1 Audio-only and Video-only (Prerecorded), level A.
For videos that have dialogue, there needs to be accurate and complete captions. These can be always on (open captions) or hideable (closed captions).
Using YouTube’s automatic captions isn’t enough as the accuracy can’t be guaranteed.
This is an accessibility requirement, meeting Success Criterion 1.2.2 Captions (Prerecorded), level A.
If the video is a live webcast or broadcast, we can use real-time text translation in captions, such as on YouTube.
This is an accessibility requirement, meeting Success Criterion 1.2.4 Captions (Live), level AA.
Videos also need to have a specific audio track that includes audio descriptions. Users must be able to select whether to use this audio track or not. You can do this by having a separate video that includes only the audio description soundtrack.
Live videos do not need audio descriptions.
This is an accessibility requirement, meeting Success Criterion 1.2.5 Audio Description (Prerecorded), level AA.
We adapt our tone depending on whether the situation is positive, negative, or neutral. Here are some examples:
You've successfully uploaded your PAPDIS file. Take a look below at what's been imported.
You're just a few clicks away from launching your new pension scheme.
You've updated your contribution percentage. Take a look at how much you already have in your pot.
You've finished everything on your checklist. Let's get started with your first upload.
Your PAPDIS upload was successful!
Your email address has been updated. Good job!
You've uploaded your PAPDIS file. Smart's just helped you keep your employees happy.
Your password has been updated securely thanks to Smart's innovative security technology.
Smart products are built with the latest technology and security, so you can set up your pension scheme quickly and securely.
Thanks for your email. We typically respond within 3 working days.
You can change how much you put into your pension each month. To do this, sign into your account and click on 'contributions', then adjust the slider.
We use the best technology for our Keystone platform to make us faster and more secure than anyone else.
Thanks for your email. We typically respond within 3 working days. Please note that in some exceptional circumstances it may take up to 7 days for an initial response, and then a further 5 working days for a full response if consultation is required from elsewhere in the company.
As per your request, please find instructions on how to change your password within this email.
We weren't able to import your PAPDIS file. This is because the 'contribution' column is blank.
We're sorry we sent your employers a postponement letter by mistake. We’ve identified what caused this to happen, and have taken steps to rectify it and ensure that it doesn't happen again.
We've cancelled your invoice payment due to a problem with your account details. Sign into your account to edit your details and we'll retry the payment shortly.
Your account is disabled. Don't worry, it's only temporary.
Error 2394 - Invalid line item 'GQE'.
You've failed to meet the eligibility criteria for enrolment in this pension scheme. To be eligible you must be in reckonable service with gross qualifying earnings of over £XX,XXX per annum.
You've uploaded your PAPDIS file with missing data.
Your payment has failed because you haven't updated your account details.
You've entered your password incorrectly.
Here are some examples of our tone of voice in action:
Field 'Date of Birth' is invalid.
Please enter a valid date of birth.
Whoops! Looks like that date of birth isn't quite right.
Invalid password entered. Try again.
Your password is incorrect. Please try again.
Oh dear! That password doesn't seem to match what we've got here. Let's have another go.
You are now registered with Smart Pension
Your account is activated. Log in to evaluate and alter your current monthly contribution levels. You may also use the navigation tools to review the latest valuation of your pension funds.
Welcome to Smart Pension
Get started by checking on how much you're contributing to your pension. Don't forget to check back often and see how your savings are growing.
Yay! You're all signed up
Come on over to the website now to check how much cash is going into your pot and see how it's doing.
This is to notify you of changes to your company pension scheme.
<Company name> has made some changes to your pension scheme.
Heads up! There's some new stuff happening.
We're contacting you to notify you that your password has been changed. If you did not request this change please contact us.
Your password has been changed. If this wasn't you, let us know.
You've got a shiny new password. If you didn't choose it, drop us a line and tell us.
Employee Engagement is acknowledged as crucial to success in modern companies.
Keeping your employees happy and engaged is key to the success of your company.
No one likes a grumpy employee. To be successful you need to keep all the folks in your company happy.
No results. Please try a different search.
If there's something you think should be included, email us (this could be to a new content guild email address, or possibly to an email that notified the #writesmart slack channel. OR just have this encourage people to talk in the slack channel).
Don't use breach –use break.
Don't use by means of – use by.
Don't use calculate –use work out or decide.
Don't use cease– use finish, stop, end.
Don't use circumvent – use get round, avoid, skirt, circle.
Don't use clarification –use explanation or help.
Don't use combine – use mix.
Don't use combined – use together.
Don't use commence– use start or begin.
Don't use communicate – use talk, write, or telephone – be specific about the method of communication.
Don't use competent – use able or can.
Don't use compile – use make or collect.
Don't use complete – use fill in or finish.
Don't use completion – use end.
Don't use comply with – use keep to or meet.
Don't use component – use part.
Don't use comprise – use make up or include.
Don't use conceal – use hide.
Don't use concerning – use about or on.
Don't use conclusion – use end.
Don't use concur – use agree.
Don't use condition – use rule.
Don't use consequently – use so.
Don't use considerable – use great or important.
Don't use constitute – use make up or form.
Don't use construe – use interpret.
Don't use consult – use talk to, meet, ask.
Don't use consumption – use amount used.
Don't use contemplate – use think about.
Don't use contrary to – use against or despite.
Don't use correct – use put right.
Don't use correspond – use write or email.
Instead of using the term costs the sum of use the term costs instead
Instead of using the term counter use the term against instead
Instead of using the term courteous use the term polite instead
Instead of using the term cumulative use the term added up, added together instead
Instead of using the term currently use the term now (or edit out) instead
Instead of using the term customary use the term usual, normal instead
Instead of using the term deduct use the term take off, take away instead
Instead of using the term deem to be use the term treat as instead
Instead of using the term defer use the term put off, delay instead
Instead of using the term deficiency use the term lack of instead
Instead of using the term delete use the term cross out instead
Instead of using the term demonstrate use the term show, prove instead
Instead of using the term denote use the term show instead
Instead of using the term depict use the term show instead
Instead of using the term designate use the term point out, show, name instead
Instead of using the term desire use the term wish, want instead
Instead of using the term despatch or dispatch use the term send, post instead
Instead of using the term despite the fact that use the term though, although instead
Instead of using the term determine use the term decide, work out, set, end instead
Instead of using the term detrimental use the term harmful, damaging instead
Instead of using the term difficulties use the term problems instead
Instead of using the term diminish use the term lessen, reduce instead
Instead of using the term disburse use the term pay, pay out instead
Instead of using the term discharge use the term carry out instead
Instead of using the term disclose use the term tell, show instead
Instead of using the term disconnect use the term cut off, unplug instead
Instead of using the term discontinue use the term stop, end instead
Instead of using the term discrete use the term separate instead
Instead of using the term discuss use the term talk about instead
Instead of using the term disseminate use the term spread instead
Instead of using the term documentation use the term papers, documents instead
Instead of using the term domiciled in use the term living in instead
Instead of using the term dominant use the term main instead
Instead of using the term due to the fact of use the term because, as instead
Instead of using the term duration use the term time, life instead
Instead of using the term during which time use the term while instead
Instead of using the term dwelling use the term home instead
Instead of using the term economical use the term cheap, good value instead
Instead of using the term eligible use the term allowed, qualified instead
Instead of using the term elucidate use the term explain, make clear instead
Instead of using the term emphasise use the term stress instead
Instead of using the term empower use the term allow, let instead
Instead of using the term enable use the term allow instead
Instead of using the term enclosed use the term inside, with instead
Instead of using the term encounter use the term meet instead
Instead of using the term endeavour use the term try instead
Instead of using the term enquire use the term ask instead
Instead of using the term enquiry use the term question instead
Instead of using the term ensure use the term make sure instead
Instead of using the term entitlement use the term right instead
Instead of using the term envisage use the term expect, imagine instead
Instead of using the term equivalent use the term equal, the same instead
Instead of using the term erroneous use the term wrong instead
Instead of using the term establish use the term show, find out, set up instead
Instead of using the term evaluate use the term test, check instead
Instead of using the term evince use the term show, prove instead
Instead of using the term ex officio use the term because of his or her position instead
Instead of using the term exceptionally use the term only when, in this case instead
Instead of using the term excessive use the term too many, too much instead
Instead of using the term exclude use the term leave out instead
Instead of using the term excluding use the term apart from, except instead
Instead of using the term exclusively use the term only instead
Instead of using the term exempt from use the term free from instead
Instead of using the term expedite use the term hurry, speed up instead
Instead of using the term expeditiously use the term as soon as possible, quickly instead
Instead of using the term expenditure use the term spending instead
Instead of using the term expire use the term run out instead
Instead of using the term extant use the term current, in force instead
