Style guide

On this page

• About this guide
• How we write
• Grammar and punctuation
• Links, URLs, and filenames
• Lists
• Numbers, dates and times
• Symbols, currency and abbreviations
• Headings, summaries and paragraphs
• Other content elements
• Specific words, phrases and common terms
• Enquire or complain about our use of plain language

About the guide

Attribution

This guide is based on Govt.nz's style and design guide and is reused under the Creative Commons CC-BY 4.0 licence. It also draws upon 18F's content guide.

Govt.nz's style and design guide(external link)

CC-BY 4.0 international licence terms(external link)

18F content guide(external link)

Principles and purpose

Our content and visual style should make our website:

• easy to use
• easy to read and understand
• accessible to everyone
• available on any device
• straightforward, human, authoritative, and impartial.

We document our decisions in this guide to:

• describe the content types, elements, and templates that are available
• promote consistency
• avoid rework or duplication
• explain how we apply our style and design
• provide a starting point for testing and quality assurance.

Accessibility and usability

When we make decisions about our style and design, we follow the NZ Government web standards.

NZ Government Web Standards(external link)

Style references

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

Oxford Dictionaries(external link) (set to British and World English)

Te Aka Māori Dictionary(external link)

1. How we write

This guide sets out how we write for our website.

Our goal is to make things as simple and clear as possible for the veteran community to understand.

Voice and tone

Our writing is:

• straightforward but not overly direct
• personal and human, but not casual
• authoritative, but not bureaucratic.

We:

• use plain language
• use familiar language
• use short sentences
• mostly use the active voice
• say 'you' and 'your' when talking to you
• use contractions like 'you’re' or 'you’ll'
• mark Māori words up correctly, including macrons
• use respectful, gender-neutral language.

Break up text

Large chunks of text can overwhelm readers.

We use:

• sub-headings
• bullet points
• information-carrying words at the beginning of a phrase
• the active voice.

Plain language

All our staff follow our Plain Language Standard, including on our website.

Our standard consists of 3 elements and 10 points.

‘Big picture’ elements

1. The purpose of the document is clear at the start.

2. The content supports the purpose of the document.

3. The structure of the document is clear and logical to your reader.

4. The headings are informative and clearly signpost main messages.

Language elements

5. The paragraphs are mostly short and focus on one topic.

6. The sentences are mostly short and straightforward.

7. The words are precise and familiar.

8. The tone is personal and human.

Presentation elements

9. The layout helps your reader absorb the messages quickly and easily.

10. The document is error-free and consistent with the relevant style guide.

After writing to the standard, we measure our content using the Flesch reading-ease scale. A score of 65 or above is thought to be plain English. This isn’t set in stone though — sometimes specific terms can drag the reading ease down, so we aim for a score of at least 60.

When using a reading-ease scale that measures reading age, the range aimed for should be 8–12. When using one that is based on reading grades, it should be aimed for 5–8.

Frequently asked questions (FAQs)

We try to avoid FAQs because:

• they’re hard to read and search for
• they can duplicate content
• you don't know if their question has been frequently asked
• they're rarely questions genuinely asked by the public.

If you keep asking us the same questions, we need to rewrite the content.

We may publish an FAQ section if it is the clearest way to present a large amount of information.

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.

Te Reo Māori

We use:

• plain font for Māori words — do not use italics
• macrons where required
• the same capitalisation rules for English
• the appropriate code when using the Māori language.

Example

Standard English sentence: <p>This sentence is in NZ English, which is the page's main language.</p>

A sentence that's entirely in te reo Māori: <p lang="mi">Kei roto tēnei rerenga kōrero i te reo Māori.</p>

A sentence that includes a phrase in te reo Māori: <p>Bruce is voting in the <span lang="mi">Te Tai Tokerau</span> electorate.</p>

2. 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 an em dash.

Capitals

We use capitals for proper nouns, products, and entitlements.

Example

You can apply for a Commemorative Travel Contribution if you’re ...
You can get a Veteran’s Pension from the Minister of Social Development if you’re ...

Commas

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

Example

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

Em dash

We use an em dash to separate thoughts in a sentence.

Example

Your application may be denied — you won’t get a refund if it is.

En dash

We use an en dash to:

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

Examples

10–12 items

New Zealand–Australia group

Example

Aged from 10 to 15 years.
Between 8pm and 6pm.

Hyphens

We sometimes hyphenate words to make sure their meaning is clear. We join a compound adjective when it's before a noun. We also join words in their normal order when we wish to avoid ambiguity or to give them a particular meaning.

Example

a well-known citizen

a time-consuming project

6-metre-long poles

5-monthly intervals

second-hand watch 

Apostrophes

We don’t add an extra 's' after nouns or names ending in 's'.

Example

'The business’ work' — not 'the business’s work'
'Department of Internal Affairs’ address' — not 'Department of Internal Affairs’s address'.

Quotation marks

We use 'straight' quotation marks — not ‘curly’ quotation marks.

We use single quotation marks for

• short quotations
• direct speech.

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.

Plurals

We don’t use brackets or '/s' to refer to something that could be either singular or plural, like 'Send your completed document(s) to Inland Revenue'.

We use the plural instead, as this covers both possibilities: 'Send your completed documents to Inland Revenue'.

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, you've
• mustn't, aren't, couldn't, haven't
• it'd, it'll.

3. Links, URLs, and filenames

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 homepage
• the best source of information for our users.

We don’t link to commercial websites but may link to not-for-profit organisations.

Writing links

We:

• use words only — we don’t write links as URLs. For example, we write About Veterans’ Affairs, not www.veteransaffairs.mil.nz/about-us
• 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.

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

Example

example@nzdf.mil.nz

Placement of link text

We:

• put links directly below the sentence or list they refer to
• 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.

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

Certificates need to be less than 3 months old and from an approved doctor.

Health forms and guides(external link)

Approved doctors(external link)

Opening links in a new tab or window

We don't set links to open in a new tab or window unless it's a map.

There are some other exceptions which need to be decided case by case. For example, sometimes forms will work better in a new tab so that people 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. At the moment, we don't use anchor links on our website.

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

Linking to documents

When we link to documents or publications, we:

• use the title of the document to create the link text
• the details on file type and size should be automatically done by the CMP

Example

Getting a ship into a bottle(external link)

Taking that ship out again(external link)

URLs

URLs should be:

• short
• memorable
• easy to type
• well-structured.

When creating URLs:

• use dashes to separate words
• omit articles (a/an/the)
• use the stems of verbs (/make-thing/ rather than /making-thing/)
• avoid extraneous terms.

Filenames

Use:

• hyphens to separate words
• lowercase — it’s better because it’s easier to type and to remember)
• the right extension — PDFs should have .pdf at the end, JPGs should have.jpg at the end.
• words that will be descriptive to the user — it’s better to have long descriptive filenames than short, obscure ones (summary-of-pay-gap-findings.pdf is better than paygap.pdf or smmrypgpfnds.pdf).

4. Lists

We use lists to make it easier for people to:

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

Lists are always marked with the correct HTML so they’re accessible.

We use bullet lists (coded as unordered lists) to list items or points, and number 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.

5. Numbers, dates, and times

Numbers

In general:

• we use numerals instead of words when we write numbers — this helps users scan our content
• we use commas to separate thousands when the number is 1,000 or over
• when we’re talking about numbers in the millions, we use the word 'million' instead of writing out the number in full
• we use words for first to ninth and numbers after that
• we use spaces to separate groups of numbers when we write phone numbers.

Examples

You can get a Veteran’s Pension from the age of 65.

1.8 million people voted in the referendum.

... the second referendum

... the 10th flag in the list.

Freephone: 0800 483 8372

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'
• spell out the names of days and months in full.

We use 'to' instead of an en 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

10 November to 21 December 2016

6. 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 122KB.

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.

Currency

We put both the currency code and currency symbol before any amounts of money we write.

Examples

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 use both NZ and New Zealand in our content. When we’re using NZ, it’s 'an NZ law' not 'a NZ law'. This is because NZ is pronounced with a vowel sound 'en zed'.

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).

Some acronyms are more recognisable than their full spellings. For example ACC or IRD. In such instances, the acronym is acceptable at the writer's discretion.

7. Headings, summaries, and paragraphs

Headings

We use headings:

• to describe the topic or purpose of the content
• frequently, so it's easier for users to scan a page and find the information they need
• in the correct hierarchy — Heading 1 (H1), H2, H3, and so on so that:
  • users can understand how each piece of content relates to the next
  • they're accessible for people using machine readers.

To meet accessibility standards, we don't:

• use bold text instead of a heading
• skip levels of headings
• use headings without accompanying content.

Where possible, we try to use the same headings in the same order on our site. This provides consistency and helps us to make sure there are no gaps in our content

Page titles

We give each page on the site a unique, descriptive title. Our Content Management System automatically styles them as H1.

Page titles should also:

• be active — for example 'Get a hearing aid’ rather than 'Getting a hearing aid'.
• start with a verb.

Pages that only provide information don't need to follow this pattern, for example 'What to do when someone dies'.

A-Z in page headings

These standard headings are recommended but not prescriptive adapt them as needed to make the most sense in context. We leave out or combine headings as required.

Standard headings for steps on a page in the A-Z section are:

1. Who can get this
2. What you can get
3. How to apply
4. When you get it
5. Find out more

Accordion headings

We try to use 'if' headings for those funnel accordions as much as possible. This helps users to identify whether they need to open the accordion and read the text underneath.

Summaries

Summaries introduce the content on the page and help users make a decision about whether they’re in the right place. They appear:

• under the page title
• in landing pages.

We aim to make a summary:

• less than 160 characters and spaces
• include information that might answer users' needs without them reading further — sometimes called 'fail fast'
• 1 or 2 short sentences.

Paragraphs and style

Our paragraphs are:

• left-aligned — this makes the text easier to read because it provides your eye with a constant starting point for each line
• as short as possible so they're easier to understand.

We use content elements within paragraphs to help comprehension, including bulleted and numbered lists, short sentences, and tables.

We don't use:

• italics or bold text, although there are exceptions to this
• links in the text.

Alignment

• Body text is left-aligned and ragged right.
• Text headings are left-aligned.
• Table, figure, and graph titles are left-aligned.

8. Other content elements

Images

Images on the website include feature images, graphs, infographics, and icons.

We follow the NZ Government Accessibility Guidelines when we use images. In general terms, this means that any information presented in an image must also be presented in an alternative format for people who cannot view images.

NZ Government Web Accessibility Standard(external link)

Tables

We only use a table if there's no clearer way to display the information with text.

Tables are used for data, not for layout. We try to limit the number of columns in a table.

Table column headings are left-aligned.

Accordions

People with low literacy or digital skills are often reluctant to scroll down the page on websites, a trend observed by Nielsen as well as our own user research.

Writing for lower-literacy users(external link)

In addition, a lot of government information explains cases that only apply to some users, which distracts and confuses users to whom the exceptions do not apply.

Accordions help with both of these issues.

Buttons

We use buttons as a call to action if there is a clear thing users should be doing on the page, for example, ‘submit’ or ‘apply online’.

9. Specific words, phrases, and common terms

Preferred words, phrases, and capitalisation

• 2 weeks or every 2 weeks, than fortnight or fortnightly
• advisor
• Anzac, use 'ANZAC' with all capitals only when referring specifically to the Australian and New Zealand Army Corps, which was the name given to the military formation to which the New Zealand troops at Gallipoli were attached. For all other uses 'Anzac’ should be used, including Anzac Day and reference to the 'Anzacs'.
• child support
• Community Services Card
• condition, to refer to both injury and illness
• co-operation not cooperation
• de facto (without italics)
• dependant (n), when someone is dependent on someone else
• disability (not disabled)
• district nurse, not District Nurse
• doctor, rather than GP
• driver licence, not driver's licence
• EFTPOS
• email, not e-mail
• ex gratia (not italics)
• Family Court
• First World War, not World War One
• full-time
• healthcare
• ID, for example photo ID not photo identification
• impairment compensation, not disability compensation
• injury or illness
• IRD, not Inland Revenue or IR
• login (noun or adjective)
• log-in (verb)
• Navy, Army, Air Force, the three Services must be listed in this order
• NZ citizen or permanent resident (not the other way round)
• NZ Superannuation
• older person, never elderly or senior citizen
• outside New Zealand, rather than overseas or abroad
• ‘spouse or partner’, always both
• part-time
• Qualifying Service
• Qualifying Operational Service
• Qualifying Routine Service
• self-employed
• Second World War, not World War Two
• service, operational service, and routine service in reference to "serving in the NZDF" is lowercase
• Service should be capitalised when referring to the three Services (Navy, Army, Air Force) such as Service magazine or the single Services
• Service Cemetery
• SuperGold Card, capitalised and 2 words, not 3
• support — the collective term for both services and entitlements
• travelling
• veteran, unless being used in the name of a specific entitlement then it will be capitalised (note where possible we should talk directly to the person, or refer to whether they have Qualifying Service)
• Veterans’ Affairs or VA, never VANZ
• Veteran's Pension
• Veteran SuperGold Card
• Viet Nam, unless a proper name spells it differently
• wellbeing
• Work and Income, not WINZ

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 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
• mahi
• mana
• Māori
• marae
• pā
• Pākehā
• pounamu (greenstone)
• puku
• Taonga
• Te Reo Māori
• waka
• whānau
• whāngai

Contact us if you have an enquiry or complaint about our use of plain language

The Plain Language Act 2022 applies to public service agencies and Crown agents. It encourages agencies to write clearly and consistently. 

The Act does not prevent or restrict an agency from including te reo Māori in their writing.

For any enquiries or complaints about our compliance with the Plain Language Act, email our Communications team:

VA.communications@nzdf.mil.nz