On Writing, Tech, and Other Loquacities

The collected works of Lana Brindley: writer, speaker, blogger


Leave a comment

Writing Effective Procedures

Writing procedures can be much more difficult than you’d think. We see procedures everywhere, so it’s natural to think that we should be able to write one without too much trouble. For that reason, I wanted to take you through some terrible real-life procedures. This is at least partly so we can all have a chuckle at other peoples’ mistakes, and feel a little bit better about ourselves. But it’s also because it’s a lot easier to find examples of bad procedures than good ones.

With that end in mind, I went through my junk drawer, and pulled out one or two manuals that I had lying around, and I’m going to use them as examples of what not to do as we go along.

The first thing you need to look at is whether you’re documenting a process or a procedure. It’s easy to use these terms interchangeably, but they actually mean different things. The main thing to remember is that a process can contain many procedures. A process gives an overview of tasks: you might need to install the package, configure the package, and then use the package. Overall, that’s a process. Each of those things, though, is a procedure. Procedures are instructions for doing something.

WriteProcedures

Here’s an example of a certain hand-held computer game. As you can see, the instructions for using the stylus are … step 5? Every procedure in this book is numbered. What’s happened here is each procedure in a process has been numbered, rather than each step in a procedure.

So the next thing to worry about is whether you should be using bullets or numbers. This one is a really simple test: is the order important? If the order is important, use numbers. If it’s not, use bullets. Oddly, though, we get this one wrong all the time …

WriteProcedures1

These ones should all be bullets. You don’t need to operate the product from a power source before you remove the unit from the packaging.

WriteProcedures3

Let’s try this one together: Most of these ones should be numbered, the text even tells us that. The ones on the left under “Cutting Tips” are bullets, the order isn’t important, it’s a list of tips. What about at the top under “Starting and Stopping the Trimmer”? This one probably doesn’t matter, I’d be inclined to use numbers, though, mostly because you can’t stop the trimmer unless you’ve already started it.

WriteProcedures4

And just another one, because it’s so easy: The bullets in red are fine, but then we go to numbers in the purple, and then for a little variety we throw in some upper-case letters in green. Bullets would have been for all of these.

So the next thing to worry about is whether you’re describing a concept or a task. A concept is a description, it answers the question “What do I need to know?”. A task is an action, it answers the question “What do I need to do?”. As writers, it’s much easier for us to think about things rather than tasks. Users think about tasks, though, not things. Remember the old adage about not needing a drill, but a hole? That’s the essence of this point.

WriteProcedures5

This one just has so much wrong with it it’s hard to know where to start. Considering we’re talking about concepts and tasks though, let’s start with pulling those out. I’ve marked the concepts in blue, and the tasks in purple. To add insult to injury, we also have numbers where we should have bullets (in red), because this really is such a hodge-podge of information that there’s no way the order is important. Just to round things off, we also have a typo, and a vaguely insulting term about our children (in yellow).

But looking at that brings me nicely to the next point, which is about the level of detail. Make sure you don’t suddenly change depth in the middle of your procedure. If you find yourself doing this, you might actually need to do more than one procedure, or consider whether you’re actually writing a process. This one is best explained by example:

WriteProcedures6

This certainly isn’t the worst example I could have picked, but it’s interesting all the same: a few of the steps here go into detail about some extra function that your product may or may not have (in yellow), while others are as simple as “open the velcro strap” (in blue). We also have process/procedure issues here, with procedures being numbers in order, and steps getting lowercase letters (in red). This is just confused by the photo references typed in red, and both angle brackets *and* square brackets being used. We also have a few stray bullets in one step. And having said all that, I’ll remind you that this is for a pair of boots. Admittedly, slightly more complicated boots than you’re wearing today, probably, but they’re just boots in the end. Also, I’m more than a little disturbed about the idea of “closure and locking of the foot” (in green).

Everyone knows what anthropomorphism is, right? Someone like to explain it? Yep, it’s applying human qualities to non-human things or animals. We do this a lot, especially to animals, but we also tend to do it to computers a lot.

I went online to find these ones, since I didn’t have any good examples in my stack of manuals. It seems to be something we do almost exclusively to computers rather than appliances, but we *really* do it a lot.

WriteProcedures7

I’ll give you a pro tip: computers don’t actually *think*. They might display things, they might take a while to process commands, but they definitely do not think.

Have to say, though, that going through manuals looking for anthropomorphism does make this one sound slightly creepier than the author intended …

WriteProcedures8

Which brings me to one of my favourite words, and it should be one of your favourites too: parallelism. When you’re writing fiction, you don’t want every paragraph or sentence to start with “Then”. When you’re writing procedures, though, it’s a good thing to have each step start with “click” or “type” or something like that. When you mix it up, it might sound more interesting, but it just becomes confusing. When faced with two statements that seem to be saying different things, users often think you want them to be doing something different. Every step should start with an action, and the same action should use the same verb. Use “click” for a mouse click, “type” for typing on the keyboard, “press” for a hardware button, etc.

WriteProcedures9

This manual almost gets it completely right. Three procedures here all need to start with the same three steps. But in one procedure, they write it using different terms. Is “tilting the motor head back” a different action to “raising the motor head”?

So, finally some takeaways:

The main elements of a procedure are:

  • Main heading (‘ing’ verb)
  • Concept
  • Before you begin
  • Warnings
  • Procedure sub-heading (infinitive ‘to’ verb)
  • Numbered steps
  • Reference info
  • Related topics

And the things you really need to remember when writing:

  • Mouse or keyboard, GUI or CLI? Stick to it!
  • Verb (or location) first
  • Active voice
  • Give instructions, not suggestions
  • Complete sentences
  • Plain English

I’ve also created a handout with these for you to print and hang up somewhere, which you can download here.


This article was originally given as a public tech talk at Red Hat Brisbane, in September 2012.

Share


Leave a comment

Because That’s The Way it’s Always Been Done Around Here

The writing industry has a schism. It’s not always obvious. We like to play it down. Some deny its very existence. But one day, you’ll be happily writing away in your new job, safe in the knowledge that you have a good grasp of spelling, comma placement, the use of industry terms and jargon, and can even confidently place a semi-colon in a position of value, when it hits you: are you a prescriptivist or a descriptivist? Suddenly your bubble collapses. The ship you were happily sailing on just moments ago collapses beneath you, and you’re cast away on an ocean of meta-questions. It’s all well and good to understand the basic tenets of grammar, but why do you understand those things, and in what way do you apply them? Are you putting a comma there because it makes historical and logical sense to put it there, or are you doing it just because that’s the way it’s always been done?

Most technical writers, those who have forged their career path through a combination of traditional university-level education in the field and into-the-deep-end, on-the-ground experience will give you a quick answer: Because the style guide says so.

Others, though, have had a somewhat more bumpy journey. They might have come from other fields such as journalism or creative writing, or they just might be the sort who overthinks this type of thing. Their answer will be more considered. They will describe the history of the word you have chosen, how its spelling and usage has changed over time, how the impact of technology has shaped its use, and how it fits into global trends.

Neither of these answers is wrong, although the two groups have argued (and probably will continue to argue) the point ad infinitum.

Prescriptivism is an easy answer, and the one that allows the writer to get on with things. They think “how do I handle this”, and there will be some guide – Chicago, AP, the Australian Government Style Guide, an internal document – that they can consult. They get their answer, they correct it in their work, they carry on. I have been this person.

Descriptivism is a more time-consuming method. In the absence of a font of all historical grammatical knowledge, it involves discovering historical usage, charting current usage, and predicting future usage. The answer, in many cases, is probably more ‘correct’ (or at least more considered), and the writer will certainly have a very long list of very good reasons for choosing the answer they do. It is the territory of the writer who needs to understand, not just do. I have, also, been this person.

In a recent conversation it was remarked to me that the speaker could not tell if I was in favour of neologisms or not. I argued that I am in favour of new words (and usage) entering the lexicon, but that I also feel it’s important to maintain an historical accuracy within our writing and grammar. It’s a somewhat contrary position to take, I agree. After all, new words and usage will not ever enter the lexicon unless they are used, surely? Dictionaries won’t include words just because they might be used next year. Fair point.

But, just as movies are not all science fiction, writing is not all technical, language is not all written, and audiences are not all university-educated, technically adept, native English speakers between 25 and 35. Writing needs to suit the audience, and different audiences have different expectations. This gives us a startling ability to watch language shift. Words can be used in a completely informal and slang way throughout most fiction and magazines, newspapers have historically been held to a higher standard of formality (although that is changing as the golden age of print takes hold), high-brow magazines and professional journals are expected to be quite formal, along with most technical documentation, and then academic papers hit the highest highs of formal language, with their stiff tone and impenetrable prose. But before new words are taken in at the beginning of that literary river to begin their long journey to towards the sea of obscurity, they must first be coined in the spring of neologism, and that occurs in the spoken word, and rarely in print. Take, as a simple example, the word “hello”. Originally used as an exclamation (and often historically cited as being used in hunts) or a way of gaining someone’s attention, it turned into a more formal greeting after Alexander Graham Bell’s initial plan of having people answer the telephone with ‘Ahoy’ fell through. ‘Hello’ eventually became the accepted standard, leading to call operators being referred to as ‘hello girls’ for decades, and the term itself becoming almost so banal as to not require a definition. It is interesting to note that, although ‘hello’ moved easily from almost-exclusive telephone use into a general greeting, the equivalent term  in Japanese ‘mushi mushi’ (????) has not, remaining a term used on the telephone only. Language is a living thing, and will change constantly, even in the face of criticism, denial, and plain old refusal to change.

Simply put: words begin in spoken slang, are gradually normalised through various print mediums, until time and usage turns them into stiff and ‘correct’ terms to be used until they fade into obscurity. Some fade into obscurity sooner than others, some have an amazing longevity with histories that fade into the fog of time. Technology has a tendency to speed the process up significantly, with terms such as ‘facetime’, ‘diskette’, and ‘webinar’ having had their brief golden age and are now (some would say thankfully) dying out again. It is also technology to blame for the re-purposing of words such as ‘login’, ‘instantiate’, and ‘friend’. And it is technology, I fear, that has spawned this entire debate between prescriptivism and descriptivism. It might seem strange to us now, where we are encouraged to be one or the other, but I believe that in times past, we have all been a little bit of both.

As a professional word-wrangler it is my job to understand my tools. I would expect a carpenter to fully understand saws: different blades, the angle of the teeth, the size and weight all make a difference to the final product (I imagine. I believe I sawed a piece of wood once, many years ago. These days I value my fingers too much!). I make it a point to understand my tools – words, and the grammar that binds them together – completely. As such, I enjoy taking the time to research the history of words and usage, and work out exactly why it is that I should (or shouldn’t) use them in the way that I do. To me, that’s essential knowledge that I require in order to do my job well.

On the other hand, I have a job to do. I need to get words on paper. The words I set to paper need to be accurate, they need to convey the right message, and they need to be able to be understood by my audience. They also need to be given to my readers when they need them, which means hitting deadlines. And that means that I don’t have always have the time to indulge my scholarly side and look up the history of every comma use, or fully analyse whether I should be using “shut down”, “shut-down”, or “shut down” in this particular instance. So I have to make a call: I spend time researching the important ones, the contentious ones, and the ones that will hopefully lead me to a greater understanding of other words. For the rest, I have my Chicago Manual of Style, our internal Word Usage Guide, and my dictionary. I lay my faith at the feet of the prescriptivists, but make sure I pay my tithe to the descriptivists, because who knows where all this is going to lead?

Share


Leave a comment

The Language of Change, and the Changing of Language

A conversation on the Australian Tech Writers mailing list prompted me to dig up these old blog posts from 2008 and repost them here. It was a short impromptu series of the changing face of language, and how we as wordsmiths deal with it:


Merriam-Webster – Bringing The Mondegreen To Linguistic Fanboys Everywhere

July 2008

Spotted this one on Slashdot today. Reading the comments, I came along quite a few that expressed what appears to be complete and utter dismay at the introduction of new words into the language. For example, this one:

“Even if you can guess what it means, it’s always good fun to pounce on neologisms and jargon and grill the user why they are using them instead of a more traditional word.”

And then there was this one:

“my old boss used to love these damn things and every time he’d say the word “webinar” a peice of me died a little inside”

It reminds me of a time I was driving around Brisbane with a friend, it was Christmas time, and I noted a sign in front of a church that stated something along the lines of “Christmass Services”. I made an offhand comment about the mispelling, and my friend pointed out that the origin of the word indicates that it should, indeed, be spelled “Christmass” (as it derived from the Mass for Christ). The main point of her comment though was the fact that language is an ever-changing and constantly evolving beast. Wordsmiths – myself included – are often very quick to point out that something is not a word, or is a neologism, or just isn’t right for some other reason.

We all use language in different ways every day – the language we use to speak to our friends is not the same as we use to speak to our children, or to authorities. The language that we use to write emails to our friends is different to the language that we use to write a complaint to the phone company. In my case, the language that I use to write technical documentation is different to the language I use to write fiction, and is different to the language I am using to write this blog post. The most interesting thing about that is the language that I use to do all those things has changed – as I’ve gotten older, as my opinions have changed, as my knowledge has increased, as my tastes have changed, and as I’ve come across new words.

I was working on the latest fiction project last night, writing very short snippets in first person for several different characters, and consciously trying to alter the ‘voice’ of each section to suit that character. Not as easy as it sounds, but I’m reasonably pleased with the results, so far.

Language, in all its forms, shifts and changes with attitude and society. While I’ve never considered Merriam-Webster to be authoritative, and I certainly wouldn’t rely on it for any of my work, at least we ought to give them credit for trying to document the language as it is used, rather than how it ‘ought’ to be. And for that reason alone, it has a place in the world.


New Words, Old Words

August 2008

Not so long ago, I wrote this. To summarise, it was about new words adopted into the English language by the Merriam-Webster dictionary, most of which had their genesis in online culture. So it was with great joy that I came across this article which outlines some of the words that the internet has succesfully killed. It’s a lovely piece of work, I suggest you read it. My very favourite is at the top of the list – “friend”. Once a word meaning ” someone you knew, had a personal relationship with, occasionally spoke to, and frequently drank beers with” it now, according to the article, means “someone who found your email address and typed it into Facebook and/or LinkedIN. You may have met said person at a conference once, and possibly even conversed with for 5 or more minutes”. Of course, my second favourite is in there too – “startup”. Once, it meant “a company with a novel idea, service, product, or technology, and a vision on how to build that company into a successful, profitable entity”. Now, it means “a college graduate and three friends who have an incremental idea, service, product, or technology, and a vision on how to build that company such that it gets acquired by Google, Microsoft, or Yahoo (in that order), preferably within 18 months for at least 9 figures.”

The article is tongue-in-cheek – and readily admits it – but there’s a whole lot of truth in there (albeit disguised nicely behind humour). Language is evolving, and the major vehicle for change is that thing that has become so pervasive in our lives – the internet – and the culture that goes with it. Not only have new words entered – “w00t” and “mondegreen” instantly spring to mind – but ‘old’ words have had their meanings modified to fit the new medium. I maintain that it’s not a bad thing, it’s progress (whatever definition you choose to use for ‘progress’). Sometimes it seems like backwards progress, but it is nevertheless the direction we are heading. Don’t like it? That’s OK – the new generation do. And when they’re all grown up and complaining about the “young ‘ens”, well, that’s OK too. Their kids will be busy picking up the slack by then.


All The World’s A Stage, And All The Men And Women Merely Players

August 2008


In what has become a somewhat impromptu series on the evolution of the English language, I just had to mention something I read whilst on holidays last weekend. I picked up Bill Bryson’s take on the life of Shakespeare whilst away. I’ve been interested in the great mystery of Shakespeare’s life for some time now. I own a copy of Nolan’s “Shakespeare’s Face” and have read numerous other accounts (or, more accurately, guesses) of his life and works. Add to this the fact that I have been wanting to start reading Bryson’s “A Short History of Nearly Everything”, and it was a fairly predictable attraction. Not incidentally, I’m intending to read his “The Mother Tongue” shortly too.

The book is quite short, and I finished it mere days after purchase – helped along by a few days in a warm climate with no pressing demands, I might add. It is written in true Bryson style, very conversational and light hearted, and he gives a lovely (or not so lovely, depending on your take on plague and wanton violence) picture of 16th century England, and Shakespeare’s somewhat unassuming – so far as we can tell – place in it.

However, my favourite part is this discussion of some of the many words that Shakespeare (allegedly) introduced into the English language:

And there was never a better time to delve for pleasure in language than the sixteenth century, when novelty blew through English like a spring breeze. Some twelve thousand words, a phenomenal number, entered the language between 1500 and 1650, about half of them still in use today, and old words were employed in ways that had not been tried before. Nouns became verbs and adverbs; adverbs became adjectives. Expressions that could not grammatically have existed before – such as “breathing one’s last” and “backing a horse”, both coined by Shakespeare – were suddenly popping up everywhere. Double superlatives and double negatives – “the most unkindest cut of all” – troubled no one and allowed an additional degree of emphasis that has since been lost.

Bryson goes on to mention the notorious variability of spelling known in early English society, noting this little gem –

Perhaps nothing speaks more eloquently of the variability of spelling in the age than the fact that a dictionary published in 1604, A Table Alphabeticall of Hard Words, spelled “words” two ways on the title page.

Of course, it just goes to show that the language has been evolving apace for many hundreds of years. Indeed, despite the naysayers it is happening much slower now than it was back in Shakespeare’s day. I can imagine that back then there were people (perhaps among the upper, educated, classes) who complained that artists such as he were mangling the language, and doing things the wrong way, although the attitude towards English was reasonably fluid then, thanks to Latin and French being considered ‘proper’. Surely, as time went on, and English took hold first in business and legal matters, and later in the sciences, that there have been people unwilling to accept change, even as it occurs around them. Nothing has changed in that respect, I imagine, it’s just that now they have access to the internet – and a world full of people reading their opinions. Hopefully, it won’t impede the progress overly. Much as I still cringe a little at “truthiness”, “coopetition” and “incentivise”, I am completely capable of embracing the words that I like – “blogosphere” is one of my favourites, along with “jumping the shark” and “backronym”. It’s only a matter of time before the language evolves to the point that our grandchildren will be almost incomprehensible, and Shakespeare’s scribblings will have taken another step towards total obscurity.

Share


Leave a comment

The Language of Marketing

I was absently staring at a new tube of toothpaste this morning as I washed my hair. You have to look at something, right? This one declared “healthy, whiter teeth for longer”. An image of extremely long (but healthy and white) teeth filled my mind, and was immediately pushed out by the technical writer in me asking “whiter and longer than what, exactly?”

Most marketing slogans give technical writers the screaming heebie-jeebies. Not only do they make spurious and vague claims like ‘more fibre’, ‘less fat’, and ‘20% bigger’ with alarming regularity, but the adjectives! I have no doubt that it is actually possible to sell things with sentences that contain only one adjective. And if they do need more than one, I’m sure a comma wouldn’t kill them. I could rant on the folly of adverbs, too, but that is a whole different article.

Why are marketers such terrible writers?

Because customers expect spin, and spin is easy to write. All you need is a handful of adjectives and a call to action: “The new fruity refreshing Globswoddle Fizz is now available. Experience the heady taste of summer today!”

While yelling at the toothpaste tube in the morning might make us all feel better, it is not likely to turn us into marketers just to help an obviously flailing industry. I finished my marketing degree about three weeks before I decided that the marketing industry was the last place in the world I wanted to work. Eventually, I became a technical writer instead, and discovered that I had inadvertently ended up working in marketing after all. Every word we set to paper is marketing in one way or another. If it is going to be read by a customer, then it needs to sell the product. But the last thing we want to write is spin.

Why are writers such terrible marketers?

Because customers want anything but spin, and while spin is easy to write, spinless marketing is not so easy.

Spin is wanted and welcomed in places where it is expected, like product packaging and on the airwaves. When our customers read technical manuals or help text, they are looking for a solution to a problem. If they were suddenly faced with the empty promises of spin, they would lose faith in the documentation, and possibly the product.

However brutal honesty is not required, either. Product documentation should not tell customers that the product cannot fulfill their expectations. Every question needs to be anticipated and answered. The documentation must give the customer hope that their problem can be resolved, their task completed, and their sanity retained in the process.

Effective documentation never tells the customer that a product is terrible (even if it is), and it never tells a customer that they are stupid (even if they are). It never makes over-inflated claims of software brilliance, and it never assumes greater-than-average user intelligence.

Somewhere nestled in there is product documentation that shows the product in a positive light, without the hard sell. Sound easy? Like most technical writing, it sounds easy until you actually try to do it. Some tips for getting started with spinless writing:

Kick adverbs, take names.
Adverbs are a big red flag for spin. Be ruthless and cut them all out. If your sentence requires a modifier, consider what you are really trying to say. If it forms part of an instruction or description (‘The widget can be fully removed by …’), reword it to remove the adverb (‘Remove the widget by …’).

Never call anything ‘simple’.
If you tell your users that something is ‘simple’, ‘quick’, or ‘easy’, and the customer struggles with it (for whatever reason), you are essentially telling them that they fail at life. Try not to insult your users.

Mind your adjectives.
Adjectives are fine in their place. Use them only where necessary, though, and try not to use more than one at a time. (‘Locate the red button’ is fine, but avoid ‘Locate the large, shiny, red button’ that is next to the ‘tiny, silver, shiny lever’).

Know your stuff.
If you can’t describe your topic in a single short sentence, you don’t understand it well enough, and it becomes too easy to succumb to spin statements. You need to be able to give succinct and accurate descriptions for each and every component part, as well as the product as whole. If you are not able to do this, continue to research your product until you can.

Understand the enemy.
As modern humans, we are largely desensitised to advertising, simply because we are so totally immersed in it. Start noticing it. Analyse what language is used, the sentence structure they’ve employed. Work out how you would re-write it to send the same message, but without the spin.

Edit with a knife.
Never say more than you need to.

—————————————————–

This article was originally published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 1: February 2011, with the following bio:

Lana Brindley has been playing with technology since that summer in the 80’s when she spent the whole time trying not to be eaten by a grue. She has been writing since she could hold a pencil, and is currently writing technical documentation for Red Hat. Lana holds business degrees in marketing and information systems, and with any luck will have a technical communicators degree by the end of the year. She works from her home in Canberra, Australia, and occasionally leaves the house in order to berate university students and conference goers about passive sentence construction.

This post has been cross-posted to fossdocs.

Share


Leave a comment

Keeping It Stupidly Simple

Everyone has heard the old adage about the “KISS Principle: Keep It Simple, Stupid”. Easy to say, easy to remember, but often hard to do. At least, hard to do well. When we simplify our language, it often comes across as patronising, dumbed-down, or just plain rude. So how should Stupid keep it simple, without making it stupidly simple?

Consider the sentence:

“Insert the writable media into the optical disk drive.”

It’s not horribly bad as it stands, but it could be made simpler. Here’s one version:

Open the disk drawer by pressing the button on the front of the drawer. Place the CD into the tray with the label facing upwards. Close the drawer by pressing the button again. Do not force the drawer closed.”

Well, it’s simpler. We’ve lost some of the more easily-confused terms such as “writable media” and”optical disk drive”, replacing them with more common and regular words. We’ve given more specific instructions about the actual process of performing the task, which can help with understanding, and also give users more information about troubleshooting. This would be great for a manual that is introducing people to computers for the first time.

But what if I were to tell you that this instruction is to go into a Developer’s Guide, that is, a book read and used by software developers? All of a sudden, the new version of this sentence has become horribly patronising. It is safe to assume that a software developer has opened a disk drawer once or twice before, and probably doesn’t need to be given explicit instructions about where to find the button. They probably also understand the terms “writable media” and “optical disk drive”. So we’re back to where we started from. How do we simplify the sentence for this audience without speaking down to the audience?

Think about what the sentence is trying to convey. How would you explain this to someone who is sitting across the table from you? Imagine you have a friend who is a software developer. You go around to their house, and they ask you a question about this product you’re working on the manual for. How would you explain it to them? If they said “what do I do now?” would you respond by handing them a CD and saying “Insert the writable media into the optical disk drive”? Probably not. I can just about guarantee that you would say something more like this:

Put the CD into the disk drive

So there’s your answer. It’s not patronising, it’s not too complicated. It uses terms that everyone is familiar with, and isn’t couched in lengthy words and stuffy language. It gives all the information the user needs, and isn’t drowning in information we can safely assume they already know.

The problem, of course, is that keeping it simple is not always simple. Corporate language is increasingly creeping into the everyday. Keeping it out of technical documentation is becoming increasingly difficult. Of course, if the product you are documenting is called a “Synergy Manipulation Process Leveraging Suite” there’s not much you can do about that. You can, however, ensure that you give information about the product in plain language. Explain what it does (other than leverage synergies!), explain how to use it. Try standing up and reading your text out loud. Try explaining the processes and concepts to a friend and take note of the language you use. Look at each individual word and think “is there a simpler word that I can use here?”. Keep your sentences short and to the point. Avoid repetition unless it is absolutely necessary.

Just yesterday, to give a real-world example, I saw a blog-post titled “Marketing Leaders Should Help Create the Next Generation of Australian Multi-Channel Retail”. Now, I don’t even know what that means (and surely it needs another noun on the end … “retail what“?). I clicked on the link, and read the first sentence, trying to work out if it was something I might be interested in, and saw whole sentences full of nothing but corporate-speak. Needless to say, I didn’t read any more. And therein lies a valuable lesson – write for your audience, but never write for the sake of putting words on paper. Even if your audience is a group of corporate-types in suits, who live and breathe corporate-speak, don’t write an empty document, filled with empty words. Make sure you have something to say, and then say it as simply and as accurately as possible.

The pictured quotes on this page have come courtesy of Andrew Davidson’s wonderful Corporate Gibberish Generator


This blog post has been cross-posted to Professional Open Source Documentation

Share