These are my opiniated tips for writing (English) OSP texts. These tips are the principles I use when editing texts for OSP. They are divided into general writing tips, and tips that are especially relevant for OSP. I look forward to discussing writing together!
Eric
There are some common themes that always come back in writing classes. I will shortly summarise what I learned from books and patient teachers.
A lot of writing advice comes down to the concept that plain words and simple active sentences will be the most evocative. These are Anglo-Saxon ideas. As most of us have a French background, we might be used to a more flowery style. The goal is not to negate our varied background, but to know some of the customs of writing English, using them to our advantage and mould our English into an effective yet tasty blend.
A famous example of writing guidelines is Strunk & White’s 1918 the Elements of Style. The original edition is online, and while the first section is rather detailed and hard to read, the second section ‘Elementary Principles of Composition’ is still extremely useful.
In the References section you will find links to more resources.
A paragraph is a self-contained unit in which one specific part of the argument is put forward. The first sentence links the paragraph to the preceding text and introduces the point that is going to be made. The subsequent sentences are the meat of the argument: explanation, description, examples. The last sentence forms the conclusion, and should be directly related to the first sentence. The first and last sentence of a paragraph should be able to summarise the paragraph.
‘Use the active voice’ is better than ‘the active voice should be used’; ‘OSP has produced a number of typefaces’ is better than ‘a number of typefaces have been produced by OSP’.
Every adverb or adjective should be scrutinised. In ‘omit needless words’, needless can not be omitted, for ‘omit words’ does not mean the same thing.
From the style guide of the Economist:
Use the language of everyday speech, not that of spokesmen, lawyers or bureaucrats (so prefer let to permit, people to persons, buy to purchase, colleague to peer, way out to exit, present to gift, rich to wealthy, show to demonstrate, break to violate). Pomposity and long-windedness tend to obscure meaning, or reveal the lack of it: strip them away in favour of plain words.
An English sentence should hardly ever have more than two commas. This is hard for French native speakers, as French has longer sentences. The French keyboard requires one to press the shift button to transform the comma into a period. The comma comes more naturally, finishing a sentence requires effort. When editing a text you wrote, you will find you will in most cases be able to cut up sentences into smaller ones.
Text between parentheses is to be avoided. The text that is between parentheses can, in most cases, be a sentence on its own.
In most cases, the present tense is more lively and direct. When talking about the past, use the present perfect. ‘OSP has made several fonts’ instead of ‘OSP made several fonts’. Or simply, use the present: ‘OSP makes fonts’.
Mixing tenses is a grammatical error:
Looking back at the archive (http://youtu.be/zLKjdUGu02A), there is a proper cheer when Tom progressively peeled, like an orange, the image he was stretching over a dodecahedron, demoing the way Laidout could be used to prepare the file to print such a shape.
In this case, the quickest fix is ‘there was a proper cheer’, because the rest of the phrase is in past tense. Since the phrase describes an event in the past, we are free to use past or present tense. The present tense is more engaging:
Looking back at the archive (http://youtu.be/zLKjdUGu02A), there is a proper cheer when Tom progressively peels, like an orange, the image he is stretching over a dodecahedron, demoing the way Laidout can be used to prepare the file to print such a shape.
The same goes for the following example, a workshop announcement:
As this year will be LGM’s 10th edition we felt the need to reflect upon the LGM and the projects that take part in it.
Since we are writing about a workshop that will still take place, present tense fits better:
As this year will be LGM’s 10th edition we feel the need to reflect upon the LGM and the projects that take part in it.
The reason for writing in present tense is that all our texts are a call to action. We are not relaying our childhood experience. We are inviting people to get to know our projects, to sign up for a workshop, to try our software, to share our principles. So any text should have a clear connection to the reader’s present.
The main principle in show, don’t tell is that you make sure the reader can draw conclusions, instead of you drawing them in their place.
Over here in OSP land, lots of good things are happening , we’ve got a lot of nice events planned for the coming months, and we're excited to be announcing them to you here.
However, who are we to say that the things are good and the events are nice? Better let the reader decide for themselves! This is better rewritten as:
We are excited to bring you a dispatch from the land of OSP, taking the opportunity to share with you our latest projects, and to bring you up to speed on the collaborations, projects and events we have lined up.
This version leaves out the ‘good’ and the ‘nice’. Note that the second version also uses ‘collaborations, projects and events’ rather than the generic ‘events’ in the first version. It is the rest of the text that will have to convince the reader the events are worthwhile!
A variant of this principle is the need to always qualify statements. A text by OSP might contains such phrases as:
Such a phrase will ring hollow if we can not make it concrete. They should always be followed by examples. Re-read your text like a four your old: are there any statements that leave you wondering “Why?”.
All of the previous tips you will often encounter in writing advice. They are general tips. I use them in every text I write or edit, not just for OSP. The following tips have to do specifically with phenomenons I have encountered in editing OSP texts.
Every text that we write references technologies and communities that might or might not be alien to our reader. It is impossible to explain every reference, but we always do so if space allows.
From our text for Grafik:
Our description of the first encounter we had with Tom would probably be similar to the one of any of the two hundred people, sitting in the audience of the Libre Graphics Meeting in Brussels, back in May 2010. Looking back at the archive (http://youtu.be/zLKjdUGu02A), there is a proper cheer when Tom progressively peels, like an orange, the image he is stretching over a dodecahedron, demoing the way Laidout can be used to prepare the file to print such a shape.
But how is the reader of Grafik Magazine supposed to know what is LGM? A short introduction will make it much more clear what kind of meeting we are talking about, and what will be the potential interest for a graphic designer. And it makes it apparent why graphic designers and software developers and people who are both might meet each other here:
Our description of the first encounter we had with Tom would probably be similar to the one of any of the two hundred people, sitting in the audience of the Libre Graphics Meeting in Brussels, back in May 2010. The Libre Graphics Meeting is an annual meeting for users and developers of Free, Libre and Open Source graphic design software. Looking back at the archive (http://youtu.be/zLKjdUGu02A), there is a proper cheer when Tom progressively peels, like an orange, the image he is stretching over a dodecahedron, demoing the way Laidout can be used to prepare the file to print such a shape.
Another example, from a news-letter:
We wrapped up summer 2014 with the second edition of the Relearn Summer School. This year’s edition saw us collaborating with the various other working groups in Variable.
Variable happens to be the name of the FLOSS Art Lab where we had our studio at the time. But how is the reader supposed to know this? This makes the sentence vague. The solution is simple:
This year’s edition saw us collaborating with the various other working groups in the Variable F/LOSS Arts Lab.
This situates the sentence, and gives enough clues for whomever wants to find out more about Variable.
Even if the writer is urged to use short phrases and plain words, it would be strange to write exactly like we talk.
Spoken language has no paragraphs; it comes as a stream of hesitations, repetitions and half-finished phrases. The density of information per word is lower (in face-to-face communication, the speaker has many other means to their disposal!). The vocabulary of a spoken text is much smaller than even the texts we consider to be ‘plain’.
A filler phrase like “That’s it for now” is not necessary in a newsletter. Care is also to be taken with metaphors and colloquialisms. An over-used metaphor like ‘going out with a bang’, or calling a group of people a ‘gang’ might look bland in writing.
One trick to not make the text sound too conversational, is limiting the use of contractions like we’ve, we’re, they’ve, aren’t. Write them out like we have, we are, they have, are not. Some contractions in a text is ok, but definitely not all of them.
OSP’s like to be creative with writing. Creating new metaphors by translating literally from the French, using in-jokes and wacky comparisons. This is what gives OSP writing a special touch, and sets it apart from the technical writing one finds in programming circles. In coming up with our own metaphors, we are following George Orwell’s advice, who stated: “Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.”
Yet OSP texts sometimes take this too far, introducing metaphors left and right that leave the reader puzzled as to how to start interpreting them. The following example is an exaggeration, intended by the OSP’s writing it to be a bit of a provocation to their co-authors. Nevertheless, he same ‘true mushroom’ vibe can be felt throughout a lot of OSP’s writing:
Ce ne sont pas de vieux singes, mais plutôt de vrais champignons de forêt auprès desquels une visite régulière nous garantit une certaine involution.
They are not old monkeys but wild mushrooms we visit regularly to nourish the involution of OSP asbl.
The role of this sentence is to explain a metaphor to us: ‘source members’. Yet instead of learning why the members are source members, we learn they are not old monkeys. Instead of learning why they would be old monkeys, we learn they are not like mushrooms. Instead of learning why they are like mushrooms, we learn that visiting them leads to a certain involution. Instead of learning what involution means, the paragraph stops.
The reader has no way to connect all these new notions! If we were to make this metaphor work, we should start at one point and make links so the reader can follow along.
We could start with this notion of involution. In English this is not a common word. What kind of involution are we talking about here? The shrinking or return of an organ to a former size? An extension of an otherwise convenient and decent system of values to its inevitable logical conclusion, with an indecent or inconvenient result? We will have to explain shortly the kind of involution we mean, because this will be the starting point for the readers interpretation.
From ‘involution’, we can find a way to link to the mushrooms. As the involution–mushroom link is going to be complicated, at this point we can probably forgot about the monkeys… And forget about the ‘source members’! If we take this analogy seriously, we better make sure they are called ‘spore members’ or any other metaphor that can be linked to mushrooms also.
Another possible road would have been to forget the whole biology/mushroom theme, and use the notion of the ‘source’. If these are source members, are they like the well on the farm? the source of a river? A book in a library? The metaphor is rich enough to be expanded upon.
What it comes down to: when you pick a metaphor, run with it. Give the reader enough tools so they can interpret it. And don’t mix the metaphor unless you really need to.
An alternative literary technique, to which the above example is related, is the non-sequitur. That is, if we make the choice to not explain. We feel tempted to add private jokes and nonsensical comparisons, that we are not really interested in explaining or bringing to their conclusions. This is an oft-employed literary technique:
A non sequitur can denote an abrupt, illogical, unexpected or absurd turn of plot or dialogue not normally associated with or appropriate to that preceding it. A non sequitur joke has no explanation, but it reflects the idiosyncrasies, mental frames and alternative world of the particular comic persona. (source)
The key to making non sequiturs work, is restraint. A non sequitur is surprising, because it doesn’t logically follow from the preceding sentences. Yet for this surprise effect to work, the other sentences do have to make sense together. Follow a non sequitur with a non sequitur, and the reader might give up trying to understand the text altogether.
The only correct use of quotation marks, except from marking quotes, is to introduce a new notion.
Artistic techniques such as remixing, montage, citation are legally grouped under the term ‘derived works’.
Another function of quotation marks is to signal the word is somehow not the right word to use. Such quotes are known ‘scare quotes’. These signal the word’s awkwardness or inappropriateness. These kinds of quotes should be avoided—if a word is not the right word, simply do not use it. Or fully assume the use of a word by leaving out the quotation marks.
Two examples of unnecessary quote marks:
As Tom developed his own Graphical User Interface Toolkit for Laidout, the software comes with a personal ‘voice’.
We fantasized over a similar tool which could ‘engrave’ images with the same fluidity and magic.
Imagine quotation marks to cause the reader to pause mentally at the quoted word. Doing so in these cases pays undue attention to the metaphor used. Any reader will be smart enough to figure out that a software program does not literally talk—and if this is too difficult for the reader to figure out, there is no reason to use the metaphor.
Being citizens of the world, our English is a mix. Our English probably uses American English, British English, Dutch English, French English and Brussels English colloquialisms. We freely mix American and British vocabulary. Our English must read oddly to both British and American speakers. Yet when it comes to spelling, we will still have to choose a specific spelling to follow.
The choice to follow American or British spelling is rather arbitrary. Out of a sense of misplaced eurocentrism I like to write in British English spelling. But American is fine too. Yet once one picks one spelling, one should follow through with it for the entire text. Otherwise it will read awkward. Luckily, the spelling checker in your Word Processor will be able to handle your preferred spelling.
The differences in spelling are not all that great. One of the most obvious differences is that an American event is ‘organized’ by an ‘organization’ whereas a British one is ‘organised’ by an ‘organisation’. This difference is the same for all words that come from French words that end in ‘-ion’. So ‘civilized/civilization’ vs. ‘civilised/civilisation’. And of course graphic designers should be wary of the difference between ‘color’ and ‘colour’. For a more exhaustive list see:
https://en.wikipedia.org/wiki/American_and_British_English_spelling_differences
Some of Strunk’s advice resurfaces in George Orwell’s Politics and the English Language. This article later formed the basis for the style guide of the Economist, a useful online resource. The style guides for the Guardian and the Telegraph are also online.
Another writer famed for his summary style is Ernest Hemingway. The Hemingway app is an online application that tries to check your text for passive voice, complicated words, long sentences and superfluous adverbs. If you prefer to learn by example, ‘The Old Man and the Sea’ is the book in which Hemingway’s style is the most plain and simple.