Guidelines for writing headings, summaries, text alternatives for visual elements (alt text) and links and formatting – including lists.
Headings
Headings help users scan content and find what they need quickly. Organise content using clear heading levels. Start each heading with keywords and keep it to the point.
Heading levels
Using correct heading hierarchies helps people using screen readers. It also supports SEO and helps people quickly scan the content on a page.
Nest headings according to importance:
- The most important heading – the page title – has the rank 1 (heading 1 or <h1>).
- Heading 2s signpost and chunk the main sections of information on a page. H2s appear in ‘on this page’ elements, to help people navigate the page.
- Headings with a lower rank start new subsections that are part of the higher ranked section.
Example:
Do not:
- use more than one h1 on a page
- skip descending heading levels (for example <h2> followed by <h4>)
- choose headings based on visual style rather than structural appropriateness.
Heading text
Headings are signposts for people and for search engines.
Most people scan a page, rather than reading it from top to bottom. Good headings help them find the information that’s relevant to them before reading in detail.
- Make your headings meaningful and concise. Include the keywords audiences are looking for to make it easy for them to find the right information.
- Use sentence case not title case, and do not include a full stop.
- Avoid using questions as headings. Starting a heading with ‘why’, ‘how’ or ‘what’ pushes your main idea towards the end of the heading.
- Do not use quote marks in headings, even if you've used them in the body copy.
Example:
<h2> Stop signs and stop lines
A 'Stop' sign and 'Stop' line control traffic at intersections.
A 'Stop' sign is a regulatory sign and must be obeyed by law.
For further advice on writing effective headings, see the Australian Government Style Manual Headings guidance.
Page titles, short titles and URL slugs
Page title
In addition to the general rules for all headings, follow these specific rules for page titles.
The page title or H1 heading is the first thing users will see on a page. Making the title clear, concise and specific helps them feel confident they’re on the right page.
Ensuring page titles are unique also helps search engines and audiences differentiate between related pages to deliver the most relevant result.
Example:
'Careers in Murrumbidgee Local Health District’ not 'Careers'.
Navigation elements such as menus, breadcrumbs and the URL also rely on the page title. You can choose to edit for the navigation context, using the short title and URL slug fields.
Short title
The short title is an optional field. Use it to create brief, contextual page titles to display in navigation menus, cards, indexes and breadcrumbs.
While page titles should be descriptive and unique, short titles should be lean and contextual.
For example, you would use ‘Careers’ as the short title for that 'Careers in Murrumbidgee Local Health District’ page.
That way, only the most salient part (Careers) will display in navigation elements where all content related to a wider sub-topic (Murrumbidgee Local Health District).
In this example, you would also use the initialism (Murrumbidgee LHD) for the short title on the parent page, to keep navigation elements clear and simple.
For example, using that short title, the breadcrumb would appear as:
Home > Departments and agencies > Murrumbidgee LHD
URL slug
The slug is the last part of the URL that appears after the final slash. It is always lowercase, with no spaces, and hyphens between words.
For example, in the URL www.nsw.gov.au/departments-and-agencies/mlhd, ‘mlhd’ is the slug.
The slug is automatically generated from your page title, or you can edit it.
If you use a short title, the slug will automatically update to match the short title.
You can also choose to create a shortened slug that is different to the short title, or without using a short title at all.
For example, Murrumbidgee Local Health District has the short title ‘Murrumbidgee LHD’ and the even shorter slug ‘mlhd’.
For information on how to use these fields in the CMS, see the help article on Using titles, short titles, URL slugs and meta tag fields.
Labelling actions versus 'how to' information
Use clear language to help differentiate between action and informational content.
Action buttons
Always begin action buttons with a verb.
Use language that invites an action. For example, ‘Apply for a licence’.
Keep text as brief as possible (2-5 words).
How-to information
For information pages that cover how-to or supporting information about a task, the headings should emphasise this descriptive or explanatory element.
For example: ‘Applying for a licence’ or ‘How to apply...’ instead of the action-oriented ‘Apply for...’
File naming for documents and images
File names have high SEO value. Using good descriptive file names helps increase the likelihood your file will rank higher in relevant search results.
Do
- Consider context and use keywords.
- Be descriptive and succinct.
- Use hyphens, not spaces, to separate lowercase words. For example, 'title-of-your-document'.
- Only include the agency name when the information is about a specific agency, for example: an annual report.
- Exclude common format words like ‘draft’, ‘letter’ or ‘factsheet’ in the file name, media title, resource page title and URL.
Do not
- Use punctuation or special characters in file names, just letters, hyphens and numerals when relevant (for example the year on an annual report).
- Include administrative information that could be confusing for the audience, for example ‘final’, ‘with SH comments’, ‘web version’.
Tip: Blank spaces in the file name get converted to characters in the URL. Besides the fact it looks messy, people might not trust that a pdf with the URL slug ‘/complaints%26handling%’ is genuine.
The same goes for special characters such as ~ # % & * { } \ : < > ? / | “.
Applying the rules
Example: for a document called 'Complaint Handling Information for Tenants Factsheet – NSW Registrar of Community Housing' we would take the following approach:
- file name: complaint-handling-information-for-tenants (all lowercase, hyphens replacing spaces, no special characters)
- media title: Complaint handling information for tenants (topical, sentence case)
- resource page title: Complaint handling information for tenants (Sentence case, consistent with media title)
- URL slug: complaint-handling-information-for-tenants (lower case with hyphens not spaces).
For full guidance, see the document naming and governance guidelines.
Alt text
Alternative text (alt text) is descriptive text that conveys the meaning and context of visual items on your webpage.
For full guidance on how to write alt text, see Adding alternative text to a file in the media library.
Links
Do:
- Use link text that clearly identifies the target of the link. This would usually be the page title or the site name.
- Put most links at the end of sentences and start with ‘why’ people would click through. (‘To express your interest, complete the EOI form’ not ‘Complete the form to express your interest.’).
- Use deep links that take users to specific content.
- Avoid unnecessary links. Only add a link when it will help the user with the immediate task they are trying to accomplish.
- Ensure everything you link to is relevant and current.
- If a link may be useful as additional context, add it as a related link at the end of the page.
Do not:
- Use links in the page summary.
- Use a URL for link text.
- Make the link text too long. Only link the main words – not the full sentence.
- Link to a homepage or high level topic when a deeper link will be more helpful or relevant. This will help the user find the right information, and by using SiteImprove we reduce the risk of missing broken links.
- Use generic terms like 'click here', 'read more' or 'more information'. If someone is using a screen reader to index the links on a page, these words will be meaningless to them.
Publications and legislation links
When linking use the name of the legislation or publication in full. For example, 'Name of Act NSW 2004' not 'the Act'.
Legislation is usually dense and difficult to read. Whenever possible, provide a plain English summary of the part of the legislation your audience needs understand.
Only link to legislation when it is a key part of the task/s the page is designed to help our customers perform or as a related link.
PDF and document links
File type information will be appended to document links automatically by the CMS.
To avoid duplication, do not add this information to document links.
For information on how to add links in the CMS, see Using links on a page.
Do you have any questions or feedback?
To ask a question or suggest an addition to the Editorial style guide, contact our content team using the webform.