Document naming and governance guidelines
Document file names, titles and metadata are important for SEO and accessibility. Follow the guidelines to create your document to ensure it meets accessibility and usability standards.
Preparing your document
Before you upload a document to the CMS, you should:
- check it is an accepted file type
- make sure you have an appropriate file name
- have added an appropriate document title and description.
Accepted file types
Your document file must be under 25MB and one of the following file types:
- Text file, file extension .txt
- Rich text format, file extension .rft
- Microsoft Word document, file extension .doc or .docx
- Adobe portable file document (PDF), file extension .pdf
- Microsoft PowerPoint, file extension .ppt, .pptx or .potx
- Microsoft Excel spreadsheets, file extension .xls or .xlsx
- Zipped (compressed) files, file extension .zip
Naming your file
Before uploading any document, create an appropriate file name.
The file name is a name used to identify a computer file and it ends with the file extension, examples include:
- my-document.pdf
- example-report.doc
- your-presentation.ppt
Your file name needs to be descriptive with hyphens between words, for example 'nsw-statutory-declaration.pdf'. When you upload your document to the CMS you will also need to enter a title in the CMS for your document, which should match the file name but without hyphens, for example 'NSW statutory declaration'.
File names have high SEO value. Good descriptive file names give search engines like Google information about the contents of the document, which increases the likelihood it will rank higher in relevant search results.
Do
When naming documents:
Consider context and use keywords.
Be descriptive and succinct.
Use the same naming pattern for a collection (for example guides, reports or policies) and putting the consistent part of the name at the beginning.
Use hyphens to separate lowercase words. For example, 'title-of-your-document'.
Use the same file name and document name for a new version. Add the date in the document content or metadata, not in the file name (unless it’s part of a series such as annual reports).
Complete the metadata fields in the document before uploading it to the CMS. The title of a PDF is the document name and can include spaces, the file name should not include spaces.
Don't
When naming documents don't use:
Blank spaces in the file name get converted to the characters %20, for example a file name of NSW_Ferries 2023 Factsheet.pdf will display as NSW_Ferries%202023%20Factsheet.pdf in the URL.
Punctuation in file names, apostrophes are converted to the characters '.
Illegal characters, such as: ~ # % & * { } \ : < > ? / | “ . (full stop).
Irrelevant or potentially confusing information,for example ‘final’, ‘with SH comments’, ‘web version’.
Date or version number:
links will break when updating content if each version of a document has a unique name
minimise duplication (in search results) by replacing the document with a new version.
How to add a title, description and metadata to a PDF file
For PDF documents you should update the file properties – you'll need an Acrobat Pro licence to do this.
You will need to edit the Document Properties, either by going to:
- File > Properties, or
- Menu > Document properties.
In the the Document Properties, Description tab, update:
- File field – the file name will normally become the URL when uploaded to the CMS.
- Title field – add a title for your document. This should match the file name. For example, if your file name is 'nsw-voting-guide.pdf' then your title should be 'NSW voting guide'. The title appears in search results and on the browser tab.
- Author field – add an author, for example ‘NSW Government.’
- Subject field – add a description for your PDF. This will appear in the site search results. If there is no subject in the properties, there is no description in the search results.
It is very important for SEO and the customer experience that there is a description added in the subject field and a title.
How to add a title and description to a Word document
To edit the title and description in a Microsoft Word document:
1. Go to File > Info.
2. Click on Show all properties, in the bottom right side of the Info screen. The properties above will expand.
3. In the additional properties fields that have expanded enter a title in the Title field and a description in the Subject field. You may choose to enter additional information in other fields.
4. Save your document when you're finished.
Example document – file name and title
Original document file name – consultation23102022_MLapproved_webversion.pdf
Suggested file name and title for upload to the CMS
Field | Notes | |
---|---|---|
CMS title (added when uploaded to the CMS) | Mulgoa Road upgrade consultation | This title is added when the file is uploaded to the CMS. The title should be descriptive and concise. |
File name | mulgoa-road-upgrade-consultation | The file name should be a variation of the title. Use all lower case and hyphens instead of spaces. |
Document title | Mulgoa Road upgrade consultation | This title is added into the PDF metadata. It should be the same as the title added to the CMS when the document is uploaded. |
Document description | The Australian and NSW Governments are planning to widen and upgrade Mulgoa Road / Castlereagh Road to support current and future traffic demands and expected growth in the area. | This description is added into the document's metadata and provides a summary of the document. |
Why the document title and description are important
Both Google and the internal search on nsw.gov.au display the document's title and description. If the document does not have a title or description, search engines will use the file name as the title and the first few lines of the text as the description. It's a poor customer experience, it creates accessibility issues and the document will not be able to rank for the terms it should.
Examples of a documents in the nsw.gov.au search results
Usability problems with documents
Downloadable documents, like PDFs, are often not accessible or as user-friendly as HTML webpages. Where possible it is usually best to convert your document to a web page such as a single or multi-page resource. Forms can be created as webforms.
Find out more about why web pages provide a better user experience than PDFs.
If you are uploading a document file try to upload single page documents (if appropriate), as these are usually more user-friendly than spreads.