Writing for the Software Sustainability Institute

Boxer training
Photo by i yunmai.

By Simon Hettrick, Deputy Director.

Writing a style guide is probably the easiest way to cause arguments and upset people - but that's part of the point. By arguing about style, we can come to an agreement on how we think content should appear.

It's important to remember that style is subjective, so never forget the Golden Rule: one should always depart from the style guide when it is necessary. The art is working out when it is necessary.

This guide is split into five sections: writing style, punctuation, images, copyright and reference.

Starting at the beginning: who are we?

We are the Software Sustainability Institute. The first time you refer to the Institute in any piece of writing, you should use our full name.

Our name's rather long, so you will find its frequent use unwieldy (the Software Sustainability Institute did this, the Software Sustainability Institute did that). Do not be tempted to use the contraction SSI unless it's absolutely necessary. Abbreviations and acronyms plague academia like locusts, and they're just as destructive. They sound impersonal and they cause people to forget what we stand for – literally.

Instead of using the abbreviation, shorten our name to the Institute (the Software Sustainability Institute did this, the Institute did that). It has more gravitas than the SSI and it reminds people that we are an institute - not just some transient project.

Colours and fonts

The font used in the Institute's logo is Consolas. On the website, we use Lato, and in other publicity materials, we tend to use Proxima Nova or Helvetica.

The red colour used in Institute branding has the coding R=213, G=26, B=34. Check the Institute's brand guidelines for more information.

Writing style

AllTheRightNotes.jpgGeneral style

There are many, many resources that discuss writing style. My favourite two, easy-to-read books are listed below in the reference section. There is no way that I can better what they have to say, so I'll be brief in my discussion of what we want from our writing.

The key advice is: be natural.

Try and write in the way that you'd talk to someone: use contractions where appropriate, stay away from formal versions of words (use rather than utilise) and do not use the third person. Imagine that you're explaining something to a friend, because that will make your writing more inviting and enjoyable to read.

This departure from stuffy writing practices also applies to nonsensical rules of grammar. If ending a sentence in a preposition sounds natural - do it (I invoke Churchill on this one "This is a rule up with which we should not put."). And split all the infinitives you like.

The best way to get an idea of the Institute's writing style is simply to read some of the website – especially the blog and the guides.

Start at the end and then work to the start

If you are used to writing for research, you will start with the facts, build up an argument and then come to a conclusion. It's a pyramid structure with lots of facts at the bottom all building up to a shining conclusion at the top. This structure does not work for blog posts, articles or any other writing that requires you to grab the reader's attention, because it takes too long to get to the point. Most people don't have much time, and they do not want to waste any of it reading something that doesn't interest them.

In your first paragraph you should cover your entire story: the who, what, where, how and why. This allows the reader to decide whether to continue reading. Once you've got the reader's attention, you can start to construct your argument. In fact, it's a good idea to picture all your readers as incredibly busy and time-pressed, because it keeps your writing concise.

You also need a hook, which is the fact or the idea that grabs the attention of your reader. Deciding on a hook requires a bit of psychology on your part. You need something that will excite your reader, which means you need to think like your reader. What do they like, what do they hate, and what are their prejudices? If you can link to any of these, you are more likely to acquire some readers. Famously, sex and death are the two big interests of most people, and a story with a link to either of these subjects is bound to pick up readers. It's not always possible to get sex or death into an article about programming (although you would be surprised how easy it can be), so you might have to find other motivations.

A taste of your own medicine

Once you've been writing for an hour or so, you'll be working more from memory than from what you read on the page. This makes it very easy to miss mistakes. After you've written something, leave it for some time (preferably overnight) and then re-read it. You'll often be horrified by what you overlooked.

Another good way of tricking yourself into seeing errors is to change format. If you're reading from a screen, print out your work and read it.

Keep sentences short

Short sentences are easy to read. If you’ve got more than three clauses in your sentence, it’s time to question whether you should split it up.

Do or do not. There is no try.

There’s a tendency when writing for public consumption to hedge one’s bets "we aim to provide…", "we intend to describe…", "we hope to fulfil…". Writing in this way appears weak. What’s more, the weasel word doesn’t fulfil its purpose. Even if you "aim to teach", a reader will still get annoyed by a tutorial that doesn’t teach them anything.

We’re the experts, so when writing about our work we need to be confident: "this guide will provide…", "this tutorial will help…".

Prose not rows

Bullet points are evil.

Lists are perfectly acceptable in tutorials, or at any time where the only focus of the writing is to lead a user through a series of steps. Bullet points should not be used in descriptive writing. That is, where the focus is on discussing a subject and weighing up its benefits. And under no circumstances should a list be the only thing that appears under a heading (unless that heading is Shopping List).

Why not?

Lists prevent comprehension, because the writer has supplied the facts, but not the logic that ties them together. The interconnecting logic is fundamental to comprehension. Take the list, expand it into sentences and provide the linking logic between the facts. Your reader will thank you for it.

(What's more, lists are boring to read, so most people skip them.)

Sell your subject

When you title a page, you’re selling it to a market of uninterested people who will only stop to read if you spark their curiosity. In the title, don’t just try and summarise the content. Instead, think about the person who will want to read the page: what are they looking for, and what words will grab their attention? See the paragraph above about hooks.

A long, difficult-to-understand, highly specific, memory-stretching string of adjectives

There are no hard and fast rules on the number of adjectives that can be used before a noun, but there is a rule of thumb: the fewer the better.

Too many adjectives make a sentence difficult to understand because it requires a good memory on the reader's part. Many people will overload a sentence with adjectives when they are trying to be specific:

The problem with badly written, developer-led, open-developed and open-source software is...

Does the sentence need to be that specific? In the example above, it's unlikely that you need to say that the software is open source and produced in an open-development environment. If you don't need to be highly specific - don't be.

The next step is to re-order the sentence and maybe split it into multiple sentences.

If open-source software has been written badly and developed in a developer-led environment, it can suffer from a problem...

This is certainly longer than the adjective-heavy version of the sentence, but it's much clearer.

Don't continuously using the continuous

Continuous verbs (a verb that ends in –ing) crop up a lot in speech, but their use in writing tends to produce tortuous (and torturous) sentences. Instead, use the infinitive form (plead rather than pleading, nag rather than nagging). It will make your writing a lot easier to read.

Sometimes you can’t get away from the word

Some people worry about the repeated use of the same word in a piece of writing. I think this concern stems from hazy memories of over-zealous primary teachers who got upset with the limited vocabulary of children. It’s not actually good writing practice.

You should not repeatedly use a word that’s unnecessary (words like basically, however, thus). However... it will be difficult not to repeat some words: try writing anything on the Institute's website without using the word software. When this situation occurs, try to use an alternative where it sounds natural. If there is no alternative, or if an alternative sounds unnatural, then simply re-use the original word.

In fact, there are times when you should re-use exactly the same word over and over again

When describing a complicated system it is important to remove all ambiguity from your writing, so that your reader has the easiest possible time understanding what you mean. Apart from clear writing, the most important rule is to consistently re-use the exact name for each component every time that it is described.

If you have a rotating gabbleblochit you should consistently refer to it as such. If you point out a rotating gabbleblochit one minute but only a gabbleblochit the next minute, you will create in the reader's mind a question "Does he mean the same thing, or is there a rotating gabbleblochit and a non-rotating gabbleblochit?".

When a reader is trying to understand something difficult, the last thing he wants to do is decipher your pronouns:

The system comprises a rotating gabbleblochit connected to a doodle-wangy and four reciprocating wibblers - one of which is larger than the others. To prevent the system from exploding, make sure that it is screwed in tightly.

What it is the writer referring to? It might seem verbose, but it is far clearer to write:

The system comprises a rotating gabbleblochit connected to a doodle-wangy and four reciprocating wibblers - one of which is larger than the others. To prevent the system from exploding, make sure that the large reciprocating wibbler is screwed in tightly.

Pronouns make life easier for the writer, but they require the reader to remember what it your sentence is referring to. If it is not perfectly clear what your pronoun is referring to, replace it for the name of the thing that it represents.

Third time unlucky

We all know about our genetic predisposition for things occurring in threes: faith, hope and charity; snap, crackle and pop; Athos, Porthos and Aramis. It just sounds right.

That’s all well and good, but don’t fall into the trap of always saying things in threes. We don’t need to say that “This guide will provide help, guidance and advice…” when it’s much clearer to say “This guide will provide advice…”.

What do we want? Fewer abbreviations! When do we want them? ASAP!

Abbreviations should be kept to a minimum (and SSI should be virtually non-existent), because they can confuse your reader. It’s difficult to get away from abbreviations in the world of software but, if possible, try and use an alternative.

When using abbreviations, always ensure that all but the most pervasive abbreviations are expanded at least once. In almost all circumstances, the expansion should follow the first use of the abbreviation.

Don’t abbreviate words such as including (inc.) and information (info). That’s just plain lazy.

Latin abbreviations can be handy, but you should use them in the same way that people use emetics: only when absolutely necessary. If you use e.g., i.e. or etc. more than two times per page (and let’s say a page is 600 words), then you’re using them too frequently.

Language and conflict words

We use UK English. That should be fairly obviously. The Oxford English Dictionary is the dictionary of choice, but like all mainstream publications we take exception to -ize spellings, and instead use –ise. Similarly, we ignore the OED when it comes to spelling words such as organisation (not the OED's outmoded organization).

The most likely dictionary conflict to arise on the website comes from the American spelling of licence. As you will know, Americans use the same spelling for both the noun and verb form of licence, whereas we Brits use the noun form licence and the verb form license. There is one time when we should depart from this rule: when using names. Certain licences, such as the GNU General Public License, use the American spelling. In these circumstances, one should really honour the licence’s creator and use the American spelling of the name. It feels wrong, but that's the way it is.

Linking to pages on the website

Links provide further information to strengthen your argument or aid comprehension so use them liberally.

When typesetting a link, don’t paste the URL into the text and use it as the anchor for the link. In other words, don’t do this:

The Software Sustainability Institute provides a number of guides (https://www.software.ac.uk/resources/guides) covering everything from…

The above example is ugly, the long URL breaks the flow of the sentence and it also causes problems when justifying text – leading to large inter-word spaces or curious gaps at the end of a line.

The route to happy linking lies in the direction of finding a pertinent phrase - an anchor - to which the link can be added:

The Software Sustainability Institute provides a number of guides covering everything from…

If you want to make the link stand out more, use a longer phrase:

The Software Sustainability Institute provides a number of guides covering everything from…

In the 90s it was popular to use here as an anchor for a link. The 90s are dead. Plunging a here into the text irrecoverably changes the flow of the sentence. It’s also difficult for readers to work out exactly what information is being linked to. Don't use here as an anchor for a link. Instead, simply re-arrange your sentence to include a suitable anchor word or phrase.

Punctuation

WetPaint.jpgPunctuation is far too large a subject to deal with in this short guide. If you want more information, see the reference section at the end of this page. Below, I've listed the house-style choices on possibly contentious punctuation.

One space at the end of a sentence

It's not the 1920s. There is only one space at the end of a sentence.

It’s completely outmoded to use two spaces, and it's utterly unnecessary on these spangly new computers we have nowadays. Every modern typographer - without fail - agrees on the one-space rule, as do all the major style guides and all publishers.

Titles

And ye, it was decreed that only the first word in a title shall be capitalised and that all other words shall take the lower-case form (except proper nouns, of course).

Latin abbreviations

Latin abbreviations are preceded by a comma, and stops are used to show the contraction (here I make a rare departure from the Economist Style Guide). They’re not italicised.

Emphasis

Use italics to emphasise a word. Italics are also used to highlight when you’re talking about the word rather than using it: "it’s difficult to get away from the word software when working at the Software Sustainability Institute".

Relative to emboldened text, italics do not scream quite so loudly from the page, and this makes the page easier to read. Using italics for emphasis also means that you can very, very, very occasionally use bold to really emphasise a word.

Quotations

We use double inverted commas for quotations "I had a terrible education. I attended a school for emotionally disturbed teachers". For a quote within a quote, use single inverted commas.

Semi-colons

The semi-colon's a bit like a smart child. Even when they're correct, they come across as a little officious. If Orwell could write a novel without using a semi-colon, there is little argument why more than one or two should appear in a few pages of copy written for the Institute.

Still banging on about hyphens!

Many people know that I have a personal bugbear about compound modifiers – especially the phrase open source. It’s a long story.

When used as a noun, the phrase open source is two separate words "Is this software open source?", but when the phrase is used as an adjective (a compound modifier) it becomes hyphenated ‘Is this open-source software?’.

Hyphenation prevents confusion, because without the hyphen it’s difficult for the reader to determine whether we’re talking about open-source software or open source-software (what’s source-software?). To hammer the point home, I refer to the often-used example from the grammar books. Compare and contrast:

  • "This is a small-scale factory" (a factory that does not produce much)
  • "This is a small scale factory" (a small factory that produces scales)

The rules dictating hyphen use are fuzzy and open to some interpretation. Get the style guide mentioned below if you want the full story.

Images

KaleidoscopeWoman.jpgChoosing the right image

It's usually left to me to find an image to support copy. I'm perfectly happy with this arrangement, but here are a few tips just in case you'd prefer to find an image yourself.

The only purpose for the majority of images on the Institute's website is to enliven the page. This is a problem, because we deal with software and there simply aren't any exciting images of software. For that reason, one must look for a connection between the subject matter of the writing and an image.

The easiest connection is with the purpose of the software. Does it model climate change? If so, we can use an image of tidal waves, deserts, scientists with weather balloons, or even a burning forest.

Is there an abstract connection with the subject matter in general? The launch of new software? Why not use a rocket taking off? Written some good code? Why not use a laptop angel?

What not to use

Do not use any image based on a block diagram, a process diagram or - unless absolutely necessary - a logo.

Typesetting an image

Images on the Institute's website in most circumstances will measure 400 x 300 px at 72 dpi. The vast majority of images should be chosen to meet this aspect ratio or be cropped to size. There will be occasions when the image does not suit the aspect ratio rule (particularly wide or tall images, for example), and on these infrequent occasions the rule can be broken.

Where to get images

The best place to start is Flickr. Do an advanced search and select the options for images licensed under Creative Commons (make sure that you check the options for both the right to adapt and the right to use commercially). This means we can use the image for free. However, you must attribute the copyright owner. When doing this, we use the phrase "Image by...", which is arranged in the bottom, right-hand corner of the image.

Copyright

OldBailey.jpgAll images and all text that appears on the Institute's website or in any of the materials we produce must be provided to us with permission from the copyright owner. This is not a problem if you've written the text yourself. If someone else has written the text (or taken the photo or created the graphic), you must get permission from them.

If the content is licensed under some permissive licence (Creative Commons, Copyleft, etc.) then you will need to state which licence.

If you have any questions about copyright, please direct them to me (Simon).

Reference

Style guides

Check our A to Z: Editorial style guide for the Software Sustainability Institute, as it'll be useful if you're thinking of writing for us. 

There are other more comprehensive style guides out there. If you buy only one book this year, make it the Economist Style Guide. Style guides are invaluable, because they provide a single informed voice that settles arguments over grammar and typesetting. Don’t know where to use a semicolon, how to punctuate a list or typeset a word? Consult a style guide.

If you want to splash out on two books, my second recommendation is Strunk and White (The Elements of Style). It's a very enjoyable read.

Dictionary

We use the Oxford English Dictionary. You can buy a copy if you wish, but you'd be better off with the online version.

As mentioned above, the OED is a bit stuffy when it comes to some words, so remember that we use -ise rather than -ize and s rather than z in words like organisation.