Whether you’re writing a chapter, a research document, or a something else, this style guide will cover some grammar basics and standards for writing engaging content.
Use the active rather than passive voice. This will help us write concise, clear content.
Write to our readers as though you're sitting next to them having coffee, not lecturing to them from the front of the room. Studies have shown that conversational tone compels readers to pay attention and retain information: engaging your readers is the first step toward empowering them.
Which of the following statements is more memorable to you?
"You are about to start a journey where you will be visiting different planets. For each planet, you will need to design a plant. Your mission is to learn what type of roots, stems, and leaves will allow your plant to survive in each environment. I will guide you through by offering some hints."
or
"This program is about what type of plants survive on different planets. For each planet, a plant will be designed. The goal is to learn what type of roots, stems and leaves allow them to survive in each environment. Some hints are provided in the program."
The brain pays more attention when it thinks it's engaged in a conversation because it prepares to respond. You want your readers to feel that learning is a collaborative experience, not a dictatorial one. Use contractions and insert your personal style to enliven the text and compel the reader to participate.
Our voice is human. It’s familiar, it’s friendly, and it’s straightforward. We may crack jokes and tell stories, but our priority is to explain front-end tooling and help our readers get their projects done and get on with their lives. We use language that educates and empowers people without patronizing or confusing them.
Address the user as ‘you’ where possible.
If there are 2 pieces of information on a subject, how will the user know if there’s 3 and the user has missed one? We also fight with ourselves for search results if we duplicate information.
If something is written once and links to relevant info easily and well, people are more likely to trust the content.
To keep content understandable, concise and relevant, it should be:
- specific
- informative
- clear and concise
- brisk but not terse
- incisive (friendliness can lead to a lack of precision and unnecessary words) – but remain human (not a faceless machine)
- serious but not pompous
You should:
- use contractions (eg can’t)
- not let caveats dictate unwieldy grammar – eg say ‘You can’ rather than ‘You may be able to’
- use the language people are using – use Google Insights to check for terms people search for
- not use long sentences with complicated sub-clauses (Note: words ending in ‘–ion’ and ‘–ment’ tend to make sentences longer and more complicated than they need to be.)
Make sure text is gender neutral wherever possible. Use ‘them’, ‘their’, ‘they’ etc.
Focus on your readers' needs—why are they reading your book? What is motivating them to learn about the subject? Is it to impress their boss? Succeed at work? Do their jobs more efficiently so they have more free time to spend with their families (or play video games)? Anticipate their objectives so you can approach the topic in a way that resonates with your readers.
What's the one goal you have for your book or chapter?
The proposal guidelines asked you to state the goal of your book or chapter. Put this goal on a sticky note and place it on your monitor. As you write your book, refer back to it frequently. Does each page of your book contribute to this goal? If not, trim the fat (e.g., a lengthy overview on the history of your topic) where necessary; if it's not critical to your reader's understanding, cut it.
Consider your main goal for the book and then break it down into a number of mini goals—one for each chapter. Identify the building blocks you need to construct these points successfully and then make certain you have addressed each effectively. Be brave: leave out material that doesn't contribute to each chapter's goal.
Many people are visual learners because our brains can process visual information far more efficiently than words. After all, images are more memorable than text. Can you make your point visually? If you can, use line art, screenshots, tables, or code with annotations to engage your readers, giving them a respite from paragraphs of straight text.
What do you do when you explain something to a colleague but he still doesn't get it?
You explain it in a different way!
Redundancy does not mean repetition. Redundancy means conveying the same idea in an alternate way, using a different perspective or channel, such as graphics, examples, or exercises.
Commenting on the code inline offers insight without disrupting the reader's flow. For instructions on how to insert these in the manuscript, see the Production guidelines, with specific instructions found in the authoring format of your choice (MS Word, DocBook, etc.).
Which caption do you think provides more value to the reader?
"Figure 2-7. The Properties window, as you would expect, lists the properties of the control you select. You can organize the properties by category, as shown here."
or
"Figure 2-7. The Properties window."
Every element in the book is an opportunity to share your knowledge, and captions are no exception. Don't waste the caption space stating the obvious; impart a bit more knowledge to your readers.
How many times have you opened up a book that starts with an overview? Those are boring to read. Here is an example of an opening that will engage your readers: "Your boss walks in and tells you he needs a new feature added to an application by the end of the day. You realize you are in trouble: the guy who designed the application is on vacation. Now what do you do?" Scenarios provide a way for the reader to internalize a problem and become invested in learning about the solution.
Most people have the tools that make a good writer but are blissfully unaware of the rules. This section is intended to point out some very common errors and traps to avoid in your writing.
The golden rule for the most basic unit of writing is one thought per sentence. Never break this rule!
A paragraph consists of a topic sentence, followed by sentences that embellish or provide explanation of that idea. If you introduce a new idea or theme it deserves a new paragraph.
There is never a need to cram every single detail about something into one paragraph. Long paragraphs are daunting and off-putting for readers.
Short paragraphs that get to the point attract readers.
If you read a paragraph of your, or anybody else’s, work and you get to the end without remembering the first sentence this usually means two things. It is far too long and/or it has more than one theme. Put simply, it is a bad paragraph.
Academics tell you that any written essay or report must have an introduction, body and a conclusion. This is one of the reasons you don’t see too many academics running around in the business world.
According to the highly flawed academic model, a story must begin with an introduction of all the arguments. Then it must extrapolate the already introduced themes. Finally, it tells you how you arrived at the end by simply repeating the beginning. But if you tell a story properly in the first place there would be no need to explain to your reader how you got to the end.
Start, Middle and End are vastly different to Introduction, Body and Conclusion. Think of it as a journey. By its very definition, Start — Middle — End, moves you from one point to another.
However! The start of any piece of good written work should introduce the main theme in the very first sentence. Never repeat the sentence but it is an often powerful technique to finish a written piece on the same theme — coming full circle.
Again one of the most misused tools of writing. Most importantly a number of different people applying numerous differed methods of punctuation can be sloppy and presents a substandard image of our work.
Always remember punctuation is a tool to make your work easier to read not more complicated. Following is a list of punctuation marks and how they should be used.
You can get by your entire life using just the full stop and comma. You could write a book using only full stops and commas. So don’t go overboard trying to use the others — particularly if you don’t know how to apply them properly.
Your best friend, if in doubt stop a sentence. Then start a new one.
Use it as a break in a sentence between primary and secondary thoughts. It can be used to indicate a pause, like this one, before the reader continues. If in doubt use a full stop.
It’s a good idea to generally limit yourself to using colons in one of two ways, to introduce a list or before a direct quote.
The company’s products include: wombat cola, koala cooler and blowfly beer.
The Chairman stated: ‘We are very pleased with our products.’ (in this instance a comma can replace the colon)
Separates items in a list when there are multiple clauses within individual items. A semicolon can replace conjunctions but it is far simpler to use a comma.
The company has three main business units; forestry management, its original business; timber milling, acquired in 1984; and reconstituted wood products, established in 1996.
Remember, when using semicolons the word AND comes after the last semicolon
The dash is generally an informal writing tool. For the most part it is a substitute for commas. Some very good writers never use dashes, others adapt them to their writing style and only to be used in certain instances. The most effective use of the dash is to introduce an afterthought or a point that strongly reinforces the first part of the sentence.
As you can get by without using dashes you probably should. Never use a dash to introduce a list. That is the job of a colon.
Also, the dash symbol is not on your computer keyboard. The key immediately to the right of the ‘0’ is a hyphen. The dash can be found by selecting the ‘Insert’ menu the top toolbar in Microsoft Word, then select ‘Symbol’.
This joins two or more words that when compounded are common expressions.
Short-term, day-to-day, high-tech.
Hyphens also add prefixes to nouns
anti-development, non-core, 50%-owned
There are two types ‘single’ inverted commas and “double”. They mean the same thing but the double inverted comma is the most accepted.
Double inverted commas encapsulate quoted remarks, while single inverted commas highlighted quoted words or highlight words not used in a literal sense. He said, “This is a brilliant product.”
Management stated the result was ‘very disappointing’ in light of its past performance.
He has been described as the ‘king’ of corporate failures.
These should only ever be used to explain or add information NOT to provide wordy commentaries or opinions that belong in new sentences. Correct examples are:
He is an executive at OneSteel (formerly owned by BHP).
The number of unclaimed life insurance policies in Australia has risen dramatically in the past five years (see table below)
Should be used primarily in place of inverted commas. For most purposes, limit italics to the description of proper names.
PBL’s leading magazine titles include: The Developer, Cleo and Developer’s Weekly.
The greatest misconception about these is that the ‘bullet’ in bullet point is a noun describing the punctuation mark, or pointer, that introduces a phrase or sentence. It is a metaphor used to describe the point you are making, i.e. it is a fast, snappy point — just like a bullet.
Bullet points can be very useful in highlighting points or summarising arguments. But remember they should:
- be short;
- not introduce new lines of argument;
- each tie in to the phrase that introduces them;
- be in lower case, as each statement ties into the qualifying phrase; and
- be separated by semi-colons.
In some instances, bullet points can be used to introduce a list in which case they should read thus. Note, full stops are not required because these bullet points are not sentences
The main points of this course are as follows:
- Writing style
- Tools of writing
- Rules of writing
- Punctuation
These are often used and most often misused. An ellipsis is literally a break in a sentence, or an omission which would otherwise clarify the meaning of the sentence or phrase. It is not a vague piece of stylised punctuation; it is proper punctuation and is always three full stops separated by single spaces (from each other and any text that appears on either side).
There are two common uses for spaced ellipses; to emphasise a point, where the intention is to leave the reader contemplating that point and to join two abbreviated direct quotes. In the second case spaced ellipses can be used to edit a quote where by the ellipses replace text. Examples are:
The end of the beginning . . .
He said: “This was a crucial episode in the history of this organisation . . . I have no doubt we will emerge stronger.”
What do you do when faced with such sections? You flip to the following pages, looking for something that matters to you. History lessons can be interesting, but the information is rarely critical to understanding the topic. And overviews are not compelling because they don't provide enough depth or instruction to be useful. Keep the readers' motivation in mind and omit material that isn't necessary for their needs.
In your proposal you emphasized how your book is different. One way to make sure this is true is by using cool, unique examples, not the same old, tired ones.
Too much text without visual breaks
There's nothing worse then staring at a page full of dense, plain text. Even if the content is interesting, the reader's brain will soon realize it's immersed in a non-fiction book—full of facts and instructions—and start to seek distractions.
Break up the approach and make the process of reading your book easier by including visual or illustrative elements, such as bullet points, illustrations, sidebars, and code where it makes sense to do so. Your book's topic is not simple to learn (that's why there's a need for a book on it!), so ease your reader's pain by lightening up the appearance.