Voice and tone
Spelling and grammar
When writing, remember to:
- use simple words;
- use small paragraphs;
- structure content with headings; and
- use consistent formatting.
Language
I use Australian English, which is, for the most part, similar to British English. I do not follow any style guides but I have my own preferences towards certain spellings.
Word list
Below are the preferred ways of formatting and spelling particular words:
- file name / file type / file path
- front-end / back-end
- focusing
- home page
- Internet (capitalised)
- login (noun, e.g. "this is the login page")
- log in (verb, e.g. "log in to see more")
- re-enable
- setup (noun, e.g. "this is my setup")
- set up (verb, e.g. "set up the environment")
- username (noun, e.g. "enter your username and password")
- user name (the name of the user)
- website
- web page
- whitespace
Words to avoid
Words and phrases that may undermine the reader:
- basically;
- obviously;
- of course; and
- simply.
Words that undermine the subject:
- just
And remember; do not use:
- naughty words;
- disrespectful words; or
- naughty and disrespectful words.
Formatting
Abbreviations
Always write the expanded form of an abbreviation in its first occurrence, trailing it with the abbreviation in parentheses. The abbreviation may then be used freely in all future instances.
Example
Dates
Dates are written in the following format:
D MMMM YYYY
This is expressed as:
1 January 2019
Time
Time is written in the following format:
HH:MM T
This is expressed as:
10:55 AM
If the time is on the hour (i.e. 10:00 AM) the minutes may be omitted, provided they are not relevant:
10 AM
Audience
All content should adhere to the following principles surrounding audience.
“There is only one reader”
Avoid words that imply a group of people are reading, e.g.:
“Assume nothing”
Do not make assumptions on the reader's professional or personal backgrounds. Aim to strike a balance that will serve both beginners and veterans.
“Avoid alienation”
It is easy to accidentally imply a person is different or not normal, e.g.:
The word "those" may feel isolating to people who use assistive technologies. This sentence can be improved by changing the subject:
Citations
I use the MLA style when referencing works. There are two sections for citations:
- Works cited; and
- Bibliography.
When using inline citations, the works should be referenced under works cited. When a work is consulted but not directly cited inline, it should be referenced under the bibliography.
Citing a website
Citing a GitHub repository
To cite a GitHub repository, include the author, name of the repository, URL and date of access: