Prepared by content team, Govt.nz
Last updated: March 2015
- Section 1: Grammar
- Style
- Capital nouns
- Natural language
- White space
- Bullets
- Processes
- Dates and times
- Numbers
- Symbols and abbreviations
- Punctuation
- Straight vs curly quotation marks
- Em and en dashes
- Measurement
- Frequently asked questions (FAQs)
- Legal language
- Māori language
- Language we use
- Watch out for stray code!
- Copying and pasting
- Section 2: Links
- Minimising in-text and headline links
- Linking styles
- Links to email addresses
- The dreaded space
- Section 3: Images and files
- Naming images and files
- Linking directly to documents
- Linking to documents on external sites
- Linking to documents on our site
- Image credits
- Image alt text
- Section 4: Language we don’t use
Some style choices are optional, but we use similar patterns in similar ways all the time — consistency helps our users.
We only use a capital letter:
- at the start of a sentence
- in the first word of a heading
- for proper nouns and the titles of acts.
We don't capitalise the names of products and services unless it makes the sentence easier to read (eg Working for Families).
We capitalise:
- Working for Families
- KiwiSaver
- NZ Super.
We:
- use 'you' and 'your'
- use contractions, eg 'you're'
- are conversational — not stuffy or formal
- are gender neutral wherever possible
- call organisations and services what the general public call them, eg:
- NZ Super
- GST
- IRD.
- explain programme names, eg ‘Working for Families is money for working families’
- reflect your journey, not the internal business process.
We make our content easy for you to scan and digest by breaking up the page. We do this with:
- lists, sub headings and line breaks
- numbered lists to describe processes
- chunked content and information mapping techniques
- short paragraphs — 3 sentences max.
When we’re writing a list, we:
- start with a stem sentence that all the list items have in common
- don’t use capital letters, and only use a full stop on the last item
- sometimes use ‘and’ or ‘or’ on the second-to-last item
- check that each list item makes a full sentence with the stem.
We don’t use a stem sentence unless it helps meaning. If a list has no stem sentence, each step should start with a capital letter and finish with a full stop.
- Each point is at least one full sentence.
- Each point begins with a capital letter.
- Each point ends with a full stop.
###Processes When there’s something for you to do, we:
- break the process up into simple steps
- use a numbered list if the steps need to be done in order, eg:
- first you do this
- then you do this
- to finish the process, you do this.
We:
- write dates as day, month, year (eg 12 December 2012)
- don’t use ordinal numbers (eg 1st, 3rd etc)
- show time using a 12-hour clock, eg 5:30pm (not 1730hrs)
- show start and end times in full, eg 10am to 11am (not 10–11am)
- use 'midnight', not 00:00
- spell out the names of days and months in full, eg:
- Monday to Friday, 9am to 5pm
- 10 November to 21 December.
We show numbers numerically, not as words (except zero and one when appropriate), eg:
- children under 18
- for 3 years.
We use:
- eg, ie, etc (no full stops)
- % (not per cent)
- $
- NZD$, AUD$, USD$ if we need to indicate a currency.
- & only if it’s part of a brand name.
Remember that a webpage’s readers may enter the webpage at any point, unlike documents which are normally read from start to finish (or at least within each section).
In general:
- avoid abbreviations, as users may not read all sections on a page
- only use acronyms when they are likely to be commonly known to all likely audiences.
We don't use abbreviations. However, we do use these acronyms on Govt.nz content:
- NZ Super
- GST
- IRD
- ACC
- DOC
- DPB.
We use both NZ and New Zealand in our content. When we're using NZ, it's 'an NZ [thing]' not 'a NZ [thing]'. This is because NZ is pronounced with a vowel sound — 'en zed'.
We don’t use:
- exclamation points
- semi-colons or comma splices.
- Two independent but still related thoughts should be connected with an em-dash (—) or made into separate sentences.
We use the Oxford comma if it makes a sentence clearer or more understandable, or if we're writing a list that needs an 'and' or an 'or' to make sense.
This includes things like the family home, cars, furniture, and money like superannuation and wages.
Or:
They must:
- be 16 or older, and
- have known you for at least 6 months, or have seen your government issued photo ID (eg your driver licence).
We:
- do use curly double quotation marks, “ ”
- don’t use straight double quotation marks, " "
- don’t use single quotation marks ,' ' or ‘’.
- This is so that there is no confusion between apostrophes and single quotation marks.
Curly double quotation marks are written in HTML as:
- “ [opening curly quotation mark “]
- ” [closing curly quotation mark ”]
Em dashes:
- are used to show separate thoughts in a sentence – like this
- are written as — in HTML.
En dashes:
- are used to show ranges, eg 1-2, or 4:30-6:30
- are written as – in HTML.
We measure our content using the Flesch reading ease scale. A score of 65 or above is thought to be plain English. This is not set in stone — sometimes specific terms can drag the score down.
No FAQs. No exceptions.
If you keep asking us the same questions, we need to rewrite the content.
If we’re talking about a legal requirement, we use ‘must’, eg:
- your employer must pay you the minimum wage.
If we feel that ‘must’ doesn’t have enough emphasis, then we use ‘legal requirement/legally entitled’ eg:
- once your child is registered at school, you’re legally responsible for making sure they attend regularly.
When deciding whether to use ‘must’ or ‘legally entitled’, we consider how important it is for us to talk about the legal aspect, as well as the overall tone of voice.
If a requirement is legal but administrative, or part of a process that won’t have criminal repercussions, then we use ‘need to’, eg:
- you’ll need to provide copies of your marriage certificate.
We use the name of a specific act if it’ll help you understand — but we consider other options, eg:
- you’re entitled to a refund under the Fair Trading Act
- you’re legally entitled to a refund, or
- you’re entitled to a refund under consumer law.
We use Māori when it's appropriate. We:
- mark Māori words up correctly, including macrons
- display Departments' Māori names.
We use ‘you’ wherever possible when we're talking to you, eg:
- you can contact IRD by phone and email
- pay your fines. We can't use 'we', 'our' or 'us', as the service may not be a DIA service — we use the name of the department instead. We'll say:
- IRD will send you — not 'we'll send you' or 'you'll be sent'
- Work and Income will contact you — not 'we'll contact you' or 'you'll be contacted'.
We say:
- you can — not 'you may be able to'
- you can get — not 'you may be eligible for'
- take a copy of your [document] to [location] — not 'provide supporting documents'. Regular terms
- Prepaid.
- Full time.
- Self-employed.
- Second-hand.
- EFTPOS.
If we are copying and pasting text out of Word documents or emails, we'll make sure we don’t inadvertently copy over any strange formatting, such as different paragraph types or stray
tags.
A good way to do this is to use the 'insert as text' button in our WYSIWYG (text editor) before copying any text.
Govt.nz isn’t a wiki.
We will avoid:
- in-line links – hyperlinked words in a paragraph. Put them on a separate line instead.
- in-line links are confusing and messy, and make it more difficult for people to read and comprehend a paragraph. They can also distract the reader, or even send them off the page in the middle of a sentence.
- content editors will never hyperlink inline phrases and words consistently.
- hyperlinking headings
- this can confuse readers, who may not be sure whether the change in colour is due to style or a hyperlink.
- using unnecessary words in your hyperlinked lines
We don't:
- put URLs directly into text – we use hyperlinks instead, making sure they adhere to the Web Usability Standard
- use 'click here' – we describe the link properly and, if possible, use the title of the page we’re linking to
- use 'see', 'more', or 'more information' as the text within a link.
To test that our links work, we take out all the text on the page and just read the links — do we still know where we’ll go?
Everything we can do to make parsing our content as easy as possible, we should.
Read the Web Usability Standard
In some bulleted lists, it may not always make sense to have the list of content and then a list of links. In this case, we'll hyperlink the entire bullet list item. So:
- this is fine
- but this is not ok.
Yes
Your tax rate might change if you’re being paid a lump sum. You should make sure that you have paid the correct tax by using IRD's calculator.
IRD tax on annual income calculator
No
Your tax rate might change if you’re being paid a lump sum. You should make sure that you have paid the correct tax by using the IRD 'tax on annual income' calculator.
Yes
MPs represent you in Parliament. You have the right to contact an MP to discuss any issue.
You can contact MPs at Parliament or at their out-of-Parliament or local offices.
Yes-ish
MPs represent you in Parliament. You have the right to contact an MP to discuss any issue.
You can contact MPs at Parliament or at their out-of-Parliament or local offices.
List of current members of Parliament
No
MPs represent you in Parliament. You have the right to contact an MP to discuss any issue.
You can contact MPs at Parliament or at their out-of-Parliament or local offices.
- Find your electorate
- List of current members of Parliament
- Contact an MP
Yes
We're:
- sharing our research and the results of our usability studies
- reporting back regularly on the issues users are raising
- open-sourcing our code — it's free for anyone to use
- publishing as much content as we can using a Creative Commons CC BY 3.0 copyright licence, so anyone can reuse it
- working on improving our API to make it easier to share government information both across agencies and with the public
Read our blog post about open-sourcing our code
No
We're:
- sharing our research and the results of our usability studies
- reporting back regularly on the issues users are raising
- open-sourcing our code — it's free for anyone to use
- publishing as much content as we can using a Creative Commons CC BY 3.0 copyright licence, so anyone can reuse it
- working on improving our API to make it easier to share government information both across agencies and with the public
Yes
If you don't meet the criteria, you might be able to apply for special consideration if:
- you can't learn English
- you haven't been in NZ for enough days in the last 5 years * but you've been here for 450 days in the last 20 months
- you can’t show you intend to keep living here
- you don't meet the good character requirements, but you have evidence that you think proves you should be granted citizenship anyway
- you have exceptional circumstances relating to a recent conviction or time in prison, or
- you can prove that making you a citizen would benefit NZ.
[note: the links here were removed entirely as they pointed to pages which pointed back to this one – so were circular]
No
If you don't meet the criteria, you might be able to apply for special consideration if:
- you can't learn English
- you haven't been in NZ for enough days in the last 5 years — but you've been here for 450 days in the last 20 months
- you can't clearly show that you intend to keep living here
- you don't meet the good character requirements, but you have evidence that you think proves you should be granted citizenship anyway
- you have exceptional circumstances relating to a recent conviction or time in prison, or
- you can prove that making you a citizen would benefit NZ.
Email addresses should be:
- written out in full in lowercase
- always linked
- eg name.lastname@department.govt.nz
We don’t include any punctuation that’s not part of the email address, or add other words unless they add context (e.g. complaints, media team etc.).
We will let you know that a link is an email address. For most people, links to email addresses will open your email software, so it’s better to let you know.
Good:
For more information about Govt.nz and our work in this area email [Name of Person].
name.lastname@department.govt.nz
Or:
For more information about Govt.nz and our work in this area email:
name.lastname@department.govt.nz.
Bad: For more information about Govt.nz and our work in this area email Name of Person.
####The dreaded space
When we hyperlink an email address, we'll make sure we don’t leave any spaces before or after the address when we copy it into the hyperlink bar.
To make sure we haven’t left spaces, we'll click on the 'link' icon again while the cursor is somewhere in the hyperlinked address.
The popup box should read mailto:name@email.com not mailto:%20name@email.com or mailto:name@email.com%20.
##Section 3: Images and files ###Naming images and files All images need to have a file name that describes or names them.
- 'figure_2.jpg', ‘PresentationFINAL.pptx’ or 'dsc13551.jpg' are not acceptable.
- ‘Content doge.png’, ‘Steven Joyce 2015.jpg’ and ‘DIA Annual Report 2015.pdf’ are.
Good:
Content doge.png
Bad:
IMG_0206.jpg
All images and files need to be given a file title, when uploaded, that describes or names them.
- 'PowerPoint presentation' and 'Print' are not acceptable.
- ‘Whiteboard showing new content types’ is, for example, or ‘Infographic about how to engage with government’.
###Linking directly to documents ####Linking to documents on external sites Where possible, we’ll try to link to an external HTML page rather than a PDF (or other document) directly. This is because document links tend to break more often.
####Linking to documents on our site In some cases, we will be linking people to documents held on our own system. In these cases, the hyperlinks should always:
- include information about document filetype and size
- include this information inside the general link,
Example:
Random example document (PDF 23 kb)
NZ Web Toolkit guidance on linking to non-HTML files
###Image credits
All photos and graphics on our site need a credit.
Photos and graphics should have a note of credit in the image’s caption, if possible.
The image should be captioned as follows:
- a clear description of what’s happening in the photo
- the credit, shown in [].
Example:
Infographic showing how best to engage with government. [Meg Howie, Govt.nz]
###Image alt text Alt (or alternative) text is the text that ‘sits behind’ an image. This is a key part of ensuring images are accessible.
Alt text is created when the image is loaded to the webpage. The alt text should describe the image so that someone who can’t see it isn't missing out on the meaning associated with the image.
Charts and graphics are used to visually display information that would be difficult to do with words. This presents a challenge for writing alt text.
When possible, alt text for charts and graphics should:
- describe the type of chart and provide an over view of the data or graphical elements
- describe key trends or features.
Read the full accessibility guidelines on the New Zealand Government Web Toolkit
##Section 4: Language we don’t use We don't say:
- please — please call, please email should be call or email
- such as — we'll say eg, including or like instead
- lets you do or allows you to — it sounds like people serve the service, not the other way around
- your needs — this is a junk phrase that sounds user-friendly without having to explain why it is
- What’s the need? We’ll say that instead.
- set out — we’ll use shows
- in order to — it’s unnecessary, so we leave it out
- application — unless it’s software, it’s just a form
- simply — we’ll explain a simple process simply, rather than saying it’s simple
- it’s important to or it’s vital to — it’s not our job to tell you what’s important to you. Either you have to do something or you don’t.
We’ll also avoid business-speak and jargon, like:
- advancing
- agenda — unless it's for a meeting
- collaborate — we’ll use ‘working with’
- combating
- commit/pledge - we need to be more specific: we’re either doing something or we’re not
- countering
- deliver — pizzas, post and services are delivered, not abstract concepts like ‘improvements’ or ‘priorities’
- deploy — unless it's military or software
- dialogue — we speak to people
- disincentivise and incentivise
- drive — one can only drive vehicles, not schemes or people
- ecosystem – unless it’s about the natural environment
- empower
- entity
- facilitate — instead, we’ll say something specific about how we're helping
- focusing
- foster — unless one is fostering children
- going forward – it’s unlikely we're giving travel directions
- impact (as a verb)
- initiate
- key - unless it unlocks something, it's probably just ‘important’
- land - as a verb, unless you're talking about an aircraft
- leverage — unless in the financial sense
- liaise
- one-stop shop — we're government, not a retail outlet
- overarching
- progress — as a verb: what are you actually doing?
- ring fencing
- robust
- stakeholder — this means nothing or everything, and everyone has a different definition for it
- streamline
- strengthening — unless it’s strengthening bridges or other structures
- tackling — unless we're talking about contact sports
- transforming — what are people actually doing to change a thing?
- utilise — the word is ‘use’.