Writing Style Guide
The writing style guide is designed to inform decision when writing on behalf of Company. This is a live guide and will ensure consistency across all Company communications.
While writing, it is important to:
- Know your audience
- Know the intention of your writing
- Structure the writing
- Keep it simple
- Review and Edit
Table of contents
Formatting
Headings
Headings should be clear and concise. All content should relate to the heading or provide links to other information sources.
Article headings should not be in a question format.
Use h1 (#) for article headings.
Subheadings
Subheadings are used to highlight a specific paragraph or area of content. All content should apply to this specific subheading.
Avoid multi-tiered subheadings, use a maximum of three layers as a guide. If you need more than three layers, consider creating a separate article.
Subheadings can be in a question format where appropriate.
Use h2 (##) or h3 (###) for subheadings. Choice depends on the layer.
Notes
Information that is outside the scope of the content should be placed as a note if it necessary for the reader to understand.
Content within a note should be separate from the main content, short, and to the point. A link to more information can be provided within the note section
Hyperlinks
Consider using hyperlinks (links) to ensure all information is relevant only to the article at hand.
When an article references information that is out of scope, the reader can be linked to other information sources.
For example:
One reference for Australian spelling is the Macquarie Dictionary.
Lists
The sentence leading into a list should end in a colon (:). If each item in the list is a full sentence, capitalise the first letter and end each item with a full stop. Otherwise, if the items are fragments of a sentence, each item should start in lowercase. Use a full stop at the end of the last item.
Unordered/bullet list
An unordered list should be used when the order of the items is not important.
To create an unordered list, you should:
- end the leading sentence with a colon
- end each item with no punctuation mark
- not use a capital letter or full stop if the list items are not full sentences
- end the last item with a full stop.
To create unordered list items in markdown, use a dash (-).
Ordered/numbered list
An ordered list should be used when the order of the items is important, for example, step-by-step instructions.
Follow these steps to create an ordered list:
- You should always use a colon at the end of the leading sentence.
- Please put list items in the right order.
- Check that items which are full sentences have capital letters and full stops.
To create an ordered list in markdown, use a number followed by a full stop (1.).
Text formatting
Italics is reserved for titles and legislations, or user input.
Bold is used for emphasis.
Font and text size will be relative to the html due to the nature of markdown.
Numbers
Use words for one to nine and numerals for 10 and over
For numbers over 999, use a comma for clarity
25,000 or 3,000,000
Unless the number is paired with a symbol
3 cm or 2.75
For complex numbers, use a combination
2.5 million $57,800
Sentences
The purpose of a sentence is to deliver a single message. The average sentence will have a length of 15-20 words Company has a maximum length of 25 words.
A variety of sentence lengths will engage your reader.
Put qualifying phrases, conditions, and explanations into separate sentences.
If you want to elaborate on the same point in a new sentence, use words like ‘also’, ‘further’, or ‘however’.
If there are multiple points in a single sentence, consider using several shorter sentences, dot points, colons, or notes.
Maintain order in paragraphs.
If a sentence establishes an order, explain each item in the same order. This will help with flow and consistency.
Avoid repetition and redundancy.
Aim for lean, efficient, and concise sentences.
Writing
Acronyms
Acronyms are useful to simplify a sentence.
If you use an acronym, always spell out the title at first use, followed by the acronym in brackets.
For example:
This is the Quality Assurance (QA) process. For all QA information refer to this article.
Capitalisation
Capital letters are to be use on proper nouns.
All writing will follow sentence case, including headings.
Verbs
Verbs should be written in the present tense.
Be consistent with your tense.
Active voice
Use active voice when you want the writing to be simple, direct, clear, and easy to read.
Active voice emphasises the verb.
Sentences are structured as subject > verb > object
Passive voice is used for feedback, preserving a relationship, and when the subject is unknown.
Avoid nominalisation
Avoid nominalisation as it can distract the reader and make the writing dull or heavy.
Nominalisation is a type of ‘abstract noun’. The name of a process, technique, or emotion.
For example:
| Verb | Nominalisation |
|---|---|
| Complete | Completion |
| Introduce | Introduction |
| Provide | Provision |
| Fail | Failure |
| Arrange | Arrangement |
| Investigate | Investigation |
| Use | utilisation |
Punctuation
| Symbol name | Symbol | Main use |
|---|---|---|
| Full stop | . | End a statement or command |
| Question mark | ? | Ends a direct question |
| Exclamation mark | ! | Ends an expression of emotion |
| Comma | , | Separates words and groups of words |
| Colon | : | Signals more information to come |
| Dash | — | An informal colon |
| Parentheses | ( ) | Enclose extra information |
| Brackets | [] | Enclose words by someone other than the author |
| Apostrophe | ’ | Shows ownership or a contraction* |
| Hyphen | - | Joins two words to make another word |
| Quotation marks | ” ” | Enclose spoken words |
*Avoid using contractions.
End of sentence punctuation does not need to be included in titles, headings, subheadings, UI titles, and lists.
Tone
Use a conversational tone. Be brief and go straight to the point.
Edit out the terms ‘you can’, ’ there is’, ‘there are’, and ‘there were’.
Avoid contractions.
Use the Oxford comma.
Voice
Use second person.
For example:
You go to the library.
Types of writing
Technical content
Technical content is the information about the underlying architecture, materials, and processes required to understand existing technology. Technical content typically requires some level of existing knowledge about the content.
Technical content should include:
- Table of contents
- Revision date
- Version ID
When writing technical content, always consider the audience’s skill. Assume the reader understands the fundamentals, but never more than that. If you are unsure, provide a link to more thorough information.
Define technical terms in the context they are referred to and use frequently used words where possible.
If a term already exists, do not create a new word/phrase. Use these terms consistently throughout the article, and across Company. Use industry specific terms when writing for a professional audience.
Code examples
Code examples serve a range of scenarios:
- Simple, one-line examples
- Short, self-contained examples
- Long samples with multiple features or best practice
To create useful code examples, you should identify tasks and scenarios for your audience.
Create concise examples of key development tasks, easy to read and understand. Show the expected output within the code example.
Create sustainable and secure code examples. Follow best practice.
Ensure the code is easy to replicate and run. If possible, provide an option to copy the code directly from the page.
Writing instructions/steps
Instructions are used when a reader wants to learn. Therefore, the steps must be clear, easy to understand, and follow.
Emphasis should be placed on the main direction. Use bold to highlight key words or phrases which indicate the action or outcome.
Make sure the reader knows where the action should take place before you describe the action. If necessary, provide an introductory step to highlight the area.
Throughout step-by-step instructions, formatting and language must be consistent. Capitalise the first word of full sentences, and full stop at the end.
A separate numbered entry should be used for each step. Each step should be a complete sentence in imperative verb form, including actions that finalise the step.
Limit the number of steps to seven, and fit all steps onto the same screen.
For single-step procedures, follow the same format, but use an unordered list instead of ordered.
When writing simple sequences, you can use A > B > C format. However, this should be used
sparingly due to accessibility tool limitations.
For example:
To increase text size of a note:
- On the Whiteboard, select the notes you want to increase the size.
- From the toolbox, select the A+ icon until you reach the desired size. Click anywhere in the Whiteboard to deselect.
To move a note:
- On the Whiteboard, click and drag the note where you want.
Bias-free communication
When creating documentation, we have an obligation to respect all individuals. At Company we promote an inclusive and supportive environment. This extends to our communication.
We have a responsibility to respect diversity and promote inclusion through all our communication. As such we enforce the following guidelines for bias-free communication.
Use gender-neutral alternatives.
| Gendered term | Substitute |
|---|---|
| mankind | humanity, people |
| manpower | workforce, staff |
| manmade | synthetic, manufactured |
Do not use gendered pronouns. Instead:
- Rewrite the sentence to use they, their, or them.
- Refer to a person’s role.
- Use person or individual.
Exceptions include:
- if you are referring to a real person. Please use their preferred pronouns in this case.
- direct quotations and titles of works
- when gender is relevant. For example, diversity challenges.
When referring to accessibility challenges focus on people, not disabilities. For example: readers who have low vision or blind
When creating fictitious scenarios, include a diverse range of names and roles. Do not elude to stereotypes or generalisations and do not primarily write of Western ideals.
When including country names, be conscious of political disputes and do not mix countries states or continents.
Do not use slang or jargon as it can be confusing or offensive for the reader. Similarly, do not use loaded terms.
| Loaded term | Substitute |
|---|---|
| master | primary, main |
| slave | secondary, subordinate |
| blacklist | denylist |
| whitelist | allowlist |
| hung | stops responding |
| demilitarised zone | perimeter network |
Do not use profane/derogatory terms.
Global communication
Company is an open-source company with a potentially global reach. We value education and creating learning opportunities.
We have a responsibility to write and communicate in a way that is accessible via a translator, this is a part of our global citizenship. As such we enforce the following guidelines for global communication.
Keep your writing short and simple, break a complex sentence into multiple simple sentences. Avoid linking more than three phrases.
Use lists and tables to reduce complexity.
Include ‘that’, ‘who’, and ‘the’. These can provide clarity in the sentence structure for the reader or translator.
Particularly for machine translation:
- Use one word for a concept and be consistent.
- Avoid -ing and -ed endings.
- Use only common abbreviations.