Skip to main content

Writing

Documentation Strategy​

The purpose of documentation strategy is to help participants and public about AEMO’s participant-facing IT systems on AEMO’s website. This process ensure a single source of truth is retained. Additionally this also reduces support calls and documentation costs and prevents duplication of work and copy/paste errors.

Grammar and Writing Style​

  • Plain English: Active voice/present tense, clear, concise, and correct. Indications of passive voice are: be, being, by.
Example

The priceless van was stolen by John.

Rewrite - active voice

John stole the priceless vase.

  • Avoid the subjective tense whenever possible (that). If the sentence makes sense without that, then leave it out.
Example

I insist that he leave(s) now.

Rewrite - active voice

I insist he leave(s) now.

  • We do use the serial comma when the sentence is a list.
Example

You can have this, that, or another.

  • Users - Please avoid this word. We prefer participants or participant users.
  • Glossary terms are capitalised and included in the glossary.
  • Rules terms are included in the Rules Terms section (not italicised in the document).

UI Text Guidelines​

While there are many different topics covered under tech writer, the following topics can be helpful for UI designers. This includes guidelines for headings and titles, numbers, and spellings to ensure consistency. Following these guidelines helps create a polished and UI standard to AEMO's writing standard.

Headings and titles​

When writing copy in any UI design, the following pattern to write the title and paragraph text must be followed.

  • Title: Title Case
  • h1: Title Case
  • h2 and below: Sentence case

Numbers​

The numbers '0' and '1' are difficult for some users to read. Some typefaces make it difficult to see the difference between:

  • the letter 'O' and numberical '0'
  • the letters 'I' (capital 'i'), 'l' (lowercase 'L') and number '1'
  • The numerical '1' also sometimes is confused with the number '7'

In order to ignore this problem from existing in the first place, writing 'zero' and 'one' helps ensure all users understand that a number is being referred.

Example

Only one person agreed to it.

Their aim is zero net emissions by 2050.

They were open to discussin 3 options.

Spelling​

First reference in the Macquarie dictionary.

Style guides​

The writng style guide or manual provides content guidelines for content creators across AEMO. The guideline is for anyone who write, edits or approves AEMO content to create clear and consistent content that meets the needs of the users.

In order of priority, following priority should be taken into account when creating content for AEMO:

Style sheets​

There are terms specific to AEMO, which are not in the primary resources or style guides above. The page contains terms for lower levels: styles, spelling inconsistencies, and terms related to specific projects that are not in the primary references. Find the AEMO specific style sheet here

Terminology and glossary​

See also​

Last updated on