Best Practice for Content Writing

Posting your article

Here are some things to keep in mind when you upload your content.

Keep your article titles and summaries to the point. These are displayed in the article search results. The summary should concisely outline the contents of the article. Remember - it’s a summary, not an introduction.

Check your markdown. After posting your article, make sure everything has rendered correctly. See the Markdown Basics article if you’re unsure why something is formatted incorrectly.

Writing to teach

The Library allows us to easily share instructional content. The following tips will ensure your instructions are easy to follow.

Plan your structure

You need to understand the user’s needs before you write anything. Begin with an introduction that summarises what they user can expect to learn or achieve, and check they are ready to proceed. Are there any prerequisites that must be completed first?

Consider breaking long or complex content into subheadings. Avoid walls of text! Giant text blocks are difficult to focus on, and impossible to skim read. If the text is not broken up into digestible pieces, the reader will struggle to absorb and understand what you are trying to say.

Get to the point

Avoid filler phrases like “please note”, “N.B.” or “you may like to consider”. These rarely add meaning and often make text more difficult to read. For example, instead of “please note: this article assumes you are using Ubuntu 18.04”, write “We assume you are using Ubuntu 18.04”.

Avoid long chunks of text within brackets, such as disclaimers or explanations. If they’re important enough to be included, give them their own sentence. Alternatively, you can give them quote formatting to give them their own space like a sidenote.

Put the most important part of your sentence at the beginning by using the active voice. The active voice is described in more detail later in this article under “General writing guidelines”.

Keep it simple

Avoid overly long sentences and paragraphs. Keep your sentences specific. Avoid slang or jargon.

The Australian Government has a fantastic guide on writing in plain English, which includes terms to watch out for.

Use precise link text.

Make the destination of the link clear. Avoid meaningless terms like “click here” or “read more”. For example, instead of “download the Way of Working here” write “download the Way of Working from the Codebots website”.

General writing guidelines

Active or passive voice?

The answer to this is easy: Active! Trying to work out which one you have on the page in front of you is not so easy though, so here’s a quick trick: Try adding “by zombies” to the end of your sentence. If it makes sense, your sentence is passive. Here’s a worked example for you:

“The button is pressed” by zombies (Makes sense! Must be passive), rewrite to “Press the button”.

This works because passive sentences mention the actor last, and so we often miss it out entirely. Basic active sentence form is The actor acted on a subject. So you get things like “the zombies (actor) ate (action) the survivor (subject)”. The passive version turns it around to “The survivor (subject) was eaten (action) by zombies (actor)”.

Apostrophe or no apostrophe?

Apostrophes can be hard! So don’t assume that just because you’re about to put an S on the end of a word, it requires one. Apostrophes are only required when:

• You have taken letters out (when “you are” becomes “you’re”)
• You want to show possession (“Anakin’s laptop”).

The bit that trips people up is “it”; “its” is a pronoun (third neuter possessive pronoun, to be specific), so it works the same way as “hers” and “ours”. Only use an apostrophe with “it” if you mean “it is” or “it has”. To understand this better, check out Grammar Girl’s Apostrophe Catastrophe.

No apostrophes are needed in plurals! So no “typo’s” and no “CD’s”.

Bullets or numbers?

Is the order of the points important? If yes, use numbers. If no, use bullets. Easy!

Capitalisation

Capital letters are used for proper nouns, for abbreviated acronyms, and for any specific words we use to describe our products - the Codebots Platform, and the Entity Diagram.

Example domains

When you’re writing content, and you want to use a URL in an example, use www.example.com. This is a legitimate, working URL, that is designed specifically for use in technical documentation.

Heading style

For headings, we use Sentence case (not to be confused with sentence style). Sentence case means making only the first letter in a heading a capital letter. Proper nouns are capitalised, and certain other words (like product names), but that’s all.

Plain English

Eschew obfuscation. Meaning, never use a big word where a smaller one will work. You need to get your message across clearly, in as few words as possible, in a way that everyone can understand.

Sentence style

Vary your sentence length when writing. You can write short sentences. You can write a longer sentences that flows between various points before finally settling at a conclusion. Varying the sentence length is important. It helps your reader. You look after the limited space in a reader’s working memory with varied sentence length.

Other resources

If your issue isn’t covered here, check these resources.

• For issues related to how we present technical terms check the IBM Style Guide.
• For spelling, write in Australian English and check with the Macquarie Dictionary.
• For grammar and punctuation, check the Australian Government Style Manual.