Skip to content

Our style guide

January 2019

Contents

Introduction

How we write

Grammar and punctuation

Links

Lists

Numbers, dates and times

Symbols, currency and abbreviations

Common terms

Contact details

 

Introduction

This guide sets out how we write for data.govt.nz, and how we apply grammar and punctuation.

You can use, share and adapt this document and its contents under a Creative Commons CC-BY 4.0 International licence.

CC-BY 4.0 international licence terms

The style guide is a living document and we’ll update it whenever testing and feedback tell us there’s a better way to present the content on data.govt.nz.

This guide is based on the Govt.nz style guide.

Govt.nz's style and design guide

 

How we write

Our goal is to make things as simple and clear as possible for you, to make it easier for you to interact with our site, open data, and NZ’s data system.

Please also refer to our content strategy, which has more on our tone and personality.

Content strategy for data.govt.nz

 

Voice and tone

Our writing is:

  • straightforward
  • human
  • authoritative, and
  • impartial.

We:

  • use plain, familiar language
  • use short sentences
  • mostly use the active voice – this means we avoid using the passive tense whenever possible
  • say 'you' and 'your' when talking to you
  • use simple contractions like 'you're' or 'you'll'
  • mark Māori words up correctly, including macrons
  • use respectful, gender-neutral language.

We tell you specifically and concisely what you can do or get.

When we use the word ‘we’ on any page, we make sure it’s clear who we’re referring to at the top of that page.

Example

'You can apply for' – not 'you may be able to apply for'.

 

If we’re talking about a legal requirement, we use 'must' to give emphasis.

 

Active and passive writing

Active writing mentions the subject (the person or thing 'doing' the action) first in the sentence (for example, inflation pushed up house prices).

Passive writing mentions the object (the person or thing 'receiving' the action) first. Passive sentences often include 'by' (for example, house prices were pushed up by inflation).

Active writing is more direct and often simpler, and should be used most of the time. We’ll use short, clear sentences.

 

Frequently asked questions (FAQs)

We don't use FAQs. If you keep asking us the same questions, we need to rewrite the content.

 

Scannable content

We make our content easy for you to read and understand by:

  • using frequent, informative headings
  • creating lists
  • writing short paragraphs
  • putting links on separate lines.

 

Spelling

We use New Zealand English for our spelling (not US English).

 

References

We use these resources if we need help with spelling, grammar or punctuation issues not covered in this guide.

Oxford Dictionaries

Te Aka Māori Dictionary

 

Grammar and punctuation

We don’t use:

  • exclamation marks
  • semi-colons or comma splices – we’ll write 2 sentences instead, or separate the clauses using a dash (with a space on either side).

 

Apostrophes

We generally don’t add an extra 's' after nouns or names ending in 's'. Exceptions are okay where the alternative reads more naturally.

Example

'The business’ work' – not 'the business’s work'.

'Department of Internal Affairs’ address' – not 'Department of Internal Affairs’s address'.

 

We don’t use an apostrophe for dates, numbers, or plurals of abbreviations.

Examples

1960s.

Boeing 767s.

TVs.

 

Bold

We rarely use bold – using 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, we:

  • put key information at the start of sentences
  • use headings
  • use bullets.

 

Brackets

We limit the use of brackets and avoid using them in the middle of a sentence.

We use square brackets for format and size details of files.

Example

Algorithm assessment report – full report [PDF 10.1 MB]

 

Capitals

We only use capitals for proper nouns, such as:

  • proper names
  • brand names, including organisation or programme/initiative names
  • job titles when using the definite article, or where there could BE a definite article in use.

We use a capital letter for the Crown, and for Government and Parliament when referring to a specific government or sitting of the parliament in New Zealand. We use lower case for general references to government.

Examples

The Government introduced a new policy in 2012.

Fiscal responsibility is important for good government.

 

We don’t capitalise subject areas (for example, ‘open data’).

We only capitalise the first name of an official document, and then italicise it.

Examples

New Zealand has signed up to the Open Data Charter (ODC), which…

Stats NZ is responsible for the Open Government Data Programme (Open Data NZ).

Open Data NZ released its open data action plan in 2017, and regularly updates the accompanying implementation plan.

Open Data NZ released the Open data action plan in 2017.

 

Commas

We use the Oxford or serial comma only if it makes a list in a sentence clearer or easier to understand.

Example

This includes things like the family home, cars, furniture, and money like superannuation and wages.

 

Contractions

Contractions make text feel more conversational and friendly. They also make complex sentences easier to read – for native English speakers.

However, the punctuation can make sentences harder to read for some users. We rewrite sentences to avoid using contractions if it fits with the overall tone.

When we use them, we only use simple contractions:

  • you're
  • it's
  • can't
  • don't
  • isn't
  • there's
  • you'll
  • that's.

We don't use complex or potentially confusing contractions like:

  • should've, would've, they've
  • mustn't, aren't, couldn't, haven't
  • it'd, it'll.

We don't use any contractions on pages that are aimed at people who might not speak English well.

 

Dashes

We use a dash with a space on either side to separate thoughts in a sentence.

Example

Scans of documents – for example meetings minutes – aren’t machine readable.

 

We use a dash without spaces to:

  • show numerical ranges
  • separate proper nouns of equal value.

Examples

10–12 items.

New Zealand–Australia group.

 

We don’t use a dash when we’re using the words 'between' and 'from'.

Examples

Aged from 10 to 15 years.

Between 8pm and 6pm.

 

Headings

We use sentence case so only the first letter is upper case.

Headings in any content adhere to the proper structural order: H1 > H2 > H3 > H4 > H5.
For example, we don’t follow an H1 with an H3 or an H2 with an H4.

We never link headings.

 

Hyphens

We sometimes hyphenate words to make sure their meaning is clear.

Example

'8 year old children' could mean children who are all aged 8, or 8 children who are 1 year old.

'8-year-old children' means children who are all aged 8.

 

Plurals

We don’t use brackets or '/s' to refer to something that could be either singular or plural. We use the plural instead, as this covers both possibilities.

Example

‘Send your completed documents to Stats NZ’ – not ‘Send your completed document(s) to Stats NZ’.

 

Quotation marks

We use double quotation marks for:

  • exact quotations
  • direct speech.

We use single quotation marks for:

  • technical terms (the first time it is used)
  • classification descriptors.

 

We don’t use quotation marks around document or publication titles – we use italics to show words are part of a title instead.

 

Titles of documents or publications

We prefer to use sentence case for the titles of documents or publications. We use italics to separate document titles from their surrounding text, unless the title is a link.

Example

The Community resource kit will help you hold a discussion with your whānau, workmates or members of a community you’re part of.

More information

Writing content for everyone

GOV.UK Verify and the government Design Standards

Contractions

 

Links

We link to:

  • relevant content on our website before we link to external websites
  • the actual page with helpful content on external websites – we don’t just link to the home page
  • the best source of information for you.

 

Placement of link text

We:

  • put links directly below the sentence or list they refer to (not in the sentence)
  • don’t use bullet points to format links (we only put a link in a bullet point if it is part of a single-sentence or multi-sentence list and the whole bullet point is made into a link)
  • never link headings.

We’ve found links in sentences affect comprehension and encourage people to click away before they have read all the context.

Separating links from text also means they are easier to select on mobile devices.

Example

These could include tutorials, code examples, interactives or anything else (appropriate).

NZ data examples GitHub repo (GitHub)

More information

Maximizing the values of the link: Credibility, readability, connectivity 

Experiments in delinkification 

The web shatters focus, rewires brains

 

Writing links

We:

  • use words only
  • write descriptive links that tell you what you’ll find when you follow them – we avoid using words like 'click here'
  • don’t use repetitive phrases or words like 'read more about' or 'see' at the start of links
  • include the name of the website or organisation we're linking to if we think you'll find it useful.

We write our email addresses in full, in lower case, and link the entire address. We never link to personal email addresses.

Examples

About data.govt.nz – not www.data.govt.nz/about

Example link (Stats NZ)

example@department.govt.nz

More information

Writing link text

 

Opening links in a new tab or window

We don't set links to open in a new tab or window. However, there are some exceptions which need to be decided case by case. For example, sometimes forms will work better in a new tab so that you can see both the context and the form.

 

Using anchor links

Anchor links are links that take you to a different part of the page you're on, rather than a new page.

We often break our content up onto multiple pages so each page is focused on completing a single task or answering a single question.

In some cases, we may also use anchor links for long pages. More and more people are using our site on a mobile device, where very long pages are harder to scan and navigate. In this circumstance, anchor links would help you get to the information you need faster.

More information

Anchors OK?

Anchor links dos and don'ts

 

Broken links

When we find broken links on our site, we try to update them.

If we can’t find the new link, we remove the link from the text.

 

Linking to documents or files

When we link to documents or files, we:

  • use the title of the document to create the link text
  • include information about the document’s file type and size in square brackets at the end of the link (using KB for kilobyte, MB for megabyte, and GB for gigabyte)
  • round file sizes to 1 decimal point and use MB (not KB) for anything 1 MB or bigger.

Examples

Algorithm assessment report - full report [PDF 10.1 MB]

Algorithm assessment report - one-page summary [PDF 151 KB]

More information

Guidance on linking to non-HTML files – NZ Government Web Standards

 

Files, images and videos

When we upload any files to data.govt.nz, we make sure the filenames of the documents:

  • are unique
  • are descriptive, but as short as possible – under 28 characters, ideally
  • don’t use words like 'of', 'and', 'at', etc
  • have dates (even if only month and year)
  • are lower case
  • use hyphens instead of spaces, underscores, and any other punctuation
  • use the same construction for similar or related files.

Examples

algorithm-assessment-report-oct-2018.pdf

people-attending-open-data-day-wellington-2017.jpg

 

If uploads or embedded content are images, graphs or diagrams, we ensure there is descriptive text explaining the image, as part of accessibility best practice.

If uploads or embedded content are videos, we ensure there is a transcript of the video contained on the same webpage as the video, as well as on the video page itself on, for example, YouTube.

 

Document contents

We make sure any documents we upload – such as PDFs – contain contact information and a date within the document itself.

 

Lists

We use lists to make it easier for you to:

  • scan the page, and
  • understand information by visually separating out the points.

Lists are always marked up with the correct html so they're accessible.

We use bulleted lists (coded as unordered lists) to list items or points, and numbered lists (coded as ordered lists) for processes where the order of steps is important.

We try to:

  • keep our lists short (2–7 items)
  • only use 1 level of nesting.

 

Bulleted lists (unordered lists)

We use 2 types of bulleted lists – single-sentence lists and multi-sentence lists.

When we’re writing a single-sentence list, we:

  • start with a stem sentence that all the points have in common
  • start each point in lower case, and only use a full stop on the last point
  • sometimes use 'and' or 'or' on the second-to-last point
  • place a comma after the last word before the 'and' or 'or'
  • check that each point makes a full sentence when read with the stem.

Multi-sentence lists are introduced by a complete sentence.

  • Each point in the list is also a complete sentence.
  • Each point can be 1–3 sentences long.
  • Each point begins with a capital letter and ends with a full stop.

 

Numbered lists (ordered lists)

We use numbered lists for processes, where steps need to be done in order.

  1. First, you do this.
  2. You do this next.
  3. To finish the process, you do this.

 

Tips for more complex lists

There are 3 main options for managing more complex information in lists – for example, when there is extra information attached to some bullets and not others, or when points have nested bullets and others don’t. The main aim is to make the information as clear as possible to read.

1. Use dashes and colons

Use dashes and colons to separate the information in a single-sentence list – although not grammatically correct, it is clear to read. If you're using a lot of dashes, you might need to consider one of the other methods.

2. Use a multi-sentence list

Turn the list into a multi-sentence list.

3. Restructure the content

Re-structure the content into headings and sub-headings.

 

Numbers, dates and times

Numbers

In general:

  • we use numerals instead of words when we write numbers – this helps you scan our content
  • we use commas and no spaces to separate thousands when the number is over 10,000
  • when we’re talking about numbers in the millions, we use the word 'million' instead of writing out the number in full
  • we use spaces to separate groups of numbers when we write phone numbers.

Examples

Your child must start school by the age of 6.

1.8 million people voted in the referendum.

... the 10th flag in the list.

Freephone: 0800 101 996.

Phone: +64 4 123 4567.

 

Dates and times

We:

  • write dates as day, month, year in full
  • don’t use ordinal numbers, like 1st or 3rd, in dates
  • show time using a 12-hour clock
  • show start and end times in full
  • use 'midnight' – not '00:00’
  • use ‘midday’ – not ‘12:00’
  • spell out the names of days and months in full
  • use a comma between week day and date
  • use a slash for a 12-month period that crosses two years.

We use 'to' instead of a dash in date and time ranges as it’s easier for screen readers to read out.

Examples

12 December 2015.

5:30pm not 17:30hrs.

10am to 11am – not 10 to 11am.

Monday to Friday.

Friday, 23 November 2018.

10 November to 21 December 2016.

2016/17 for the financial year ended 30 June 2016.

 

Symbols, currency and abbreviations

Symbols

We use:

  • % – not 'percent' or 'per cent'
  • & – only if it’s part of a brand name
  • KB for kilobyte, MB for megabyte, and GB for gigabyte, for example 122 KB.

 

Currency

We put both the currency code and currency symbol before any amounts of money we write, unless the amount is for NZ dollars only.

We don't use spaces between the code, symbol and amount.

Examples

Tomato prices fell 22% to $6.90 a kg in September.

If you’re a United States citizen, you pay USD$640.

If you’re an Australian citizen it costs AUD$890.

British citizens pay GBP£420.

Japanese citizens pay JPY¥550.

 

Abbreviations

We expand all abbreviations when we use them for the first time on a page.

Example

You need to contact the New Zealand Transport Agency (NZTA).

 

We use abbreviations when they're part of the name of a service or organisation.

Examples

Stats NZ collects data about New Zealand’s environment, economy and society.

B4 School Check is a free health check for 4-year-olds.

 

To make our content easier to read, we don't use:

  • e.g.
  • i.e.
  • etc.

These are replaced with appropriate phrases including:

  • for example
  • such as
  • that is
  • and so on.

Example

Food hygiene regulations apply to food made and sold for fundraising, for example sausage sizzles.

 

We add an s without an apostrophe to make an abbreviation plural.

Example

TVs.

 

NZ and New Zealand

We use both NZ and New Zealand in our content. We use NZ in headings where using New Zealand would make the title too long.

Because NZ is pronounced with a vowel sound (en zed) sometimes we will write 'an NZ'.

 

Common terms

Spelling, capitalisation and preferred terms

We use:

  • 2 weeks or every 2 weeks – rather than fortnight or fortnightly
  • advisor, except when referring to financial adviser
  • artificial intelligence - rather than Artificial Intelligence
  • cellphone or mobile phone
  • child support
  • co-operation not cooperation
  • de facto (without italics)
  • dependant (n), when a child is a dependant of its parents
  • disability (not disabled)
  • driver licence, not driver's licence
  • EFTPOS
  • Family Court
  • financial adviser (not advisor)
  • focusing
  • full-time
  • healthcare
  • ID, for example photo ID not photo identification
  • IDI
  • illness, rather than medical condition
  • infographic
  • IRD, not Inland Revenue or IR
  • licence (noun) and licensing (verb)
  • log in (verb) to a system, or create a logon (noun)
  • outside New Zealand, rather than overseas or abroad
  • partner, rather than spouse
  • part-time
  • prepaid
  • printout (when referring to a form that can be printed out)
  • second-hand
  • self-employed
  • single, living alone rate (with a comma) for NZ Super
  • travelling
  • usable - rather than useable
  • wellbeing
  • widespread.

 

Use compared with, not compared to. ‘Compares to’ likens two things – for example, Wellington compares to San Francisco as a city.

Example

Two-thirds of people with a plan had a three-day supply of water compared with 34% of those without.

 

Māori words considered to be part of NZ English

Words considered to be part of NZ English do not need to be marked up in data.govt.nz as the Māori language.

The New Zealand Oxford Dictionary tells us which Māori words are considered to be part of NZ English.

These include:

  • Aotearoa
  • aroha
  • haka
  • hāngī)
  • hīkoi
  • hongi
  • hui
  • iwi
  • kai
  • karakia
  • kaumātua
  • Kia ora
  • Kōhanga Reo
  • mahi
  • mana
  • Māori
  • marae
  • Pākehā
  • pounamu
  • puku
  • tāngata whenua
  • taonga
  • te Reo Māori (lower case t, upper case R)
  • waka
  • whānau
  • native animals like kiwi, tuatara, kea and moa, and flora like kauri and kowhai.

 

Terms we don't use

We don't say:

  • in order to – it’s unnecessary, so we leave it out
  • 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
  • lets you do or allows you to – it sounds like people serve the service, not the other way around
  • please – 'please call', 'please email' should be 'call' or 'email'
  • set out – we use 'shows'
  • simply – we’ll explain a simple process simply, rather than saying it’s simple
  • will – when we don't need this word, for example:
    • you need a copy of your birth certificate [correct]
    • you'll need a copy of your birth certificate [incorrect]
  • your needs – state the actual needs instead.

We also avoid using jargon such as:

  • advancing
  • agenda – unless it's for a meeting
  • collaborate – we 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 – we can only drive vehicles, not schemes or people
  • ecosystem – unless it’s about the natural environment
  • empower
  • entity
  • facilitate – instead, we 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 – say what you're 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 – we state what people are actually doing to change a thing
  • utilise – we say 'use' instead.

 

Contact details

Phone and fax numbers

We always use freephone (rather than phone) for a freephone number (such as 0800, 0508).

Example

If you just need some medical advice, you can call a registered nurse on Healthline, freephone 0800 611 116.

 

If it's a New Zealand freephone, always put '(NZ only)' after the number.

Example

Freephone: 0800 611 116 (NZ only).

 

Use freefax rather than free fax.

We use cellphone, rather than cell-phone or cell phone.

We use TTY: as the label for any number that provides a text service for the deaf community.

Example

TTY: 0800 111 113.

 

Unless they're used in the middle of a sentence, phone, freephone, email and website should always have a colon after them.

Examples

Phone: +64 4 456 2390.

Email: admin@zyxvw.co.nz.

 

We don't use bullets for lists of contact details.

Examples

Freephone: 0800 123 4547.

Email: alpha@beta.com.

Not:

  • Freephone: 0800 123 4547.
  • Email: alpha@beta.com.

 

We write phone numbers with non-breaking spaces between the groups of numbers (a non-breaking space keeps the whole number on 1 line – in HTML it's coded as '& nbsp ;'). We're flexible about how the numbers are grouped – we're guided by the agency's style.

We include the plus sign and the international country code with phone numbers.

Examples

+64 4 098 7654.

+64 21 857 345.

+49 89 31 76 07.

 

Email

We don't include macrons in email addresses, even if the user does, because at this point in time most email clients can't cope with them.

 

Street addresses

We write Avenue, Corner, Drive, Road, Street, Terrace in full.

We use dashes without spaces between street numbers.

Example

112–114 Lambton Quay.

 

For street names such as 'The Terrace', 'The Square', 'The Octagon' the 'The' is always capped.

We write a street address as:

[level or floor] [building name]

[street number and name]

[suburb]

[town or city]

We don't include New Zealand at the bottom of street addresses, but we do include the country name if the street address is in another country.

We use macrons in town or city names if the local council does. We are guided by the NZ Address and Postcode Finder for macrons on Māori street names.

NZ Post – Address & Postcode Finder

 

Postal addresses

We use 'PO Box' or ‘Private Bag’ and then the number. There should be no spaces or punctuation in the number.

We use 'DX:' and then the number.

Examples

PO Box 234567 – not PO Box 23-4567 or PO Box 23 4567.

Private Bag 2922.

 

Every postal address must have:

  • a postal code
  • 'New Zealand' or the name of the country at the end of the address.

NZ Post – Address & Postcode Finder

 

If there is any question around address styles, we refer to the Address Standards set out by NZ Post.

NZ Post – Standards and Guides

Related content

Top