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

Toys

Gillard is our new PM

Image from The Punch

Time to tell Mum about privilege, EFA!

I have loved and supported Electronic Frontiers Australia (EFA) for many, many years. The love affair began back in uni, and coincided with my discovery of open source software. The power of freedom (as in speech) was heady and strong back in those days. Today, in many ways, it still is. Right now the fight is not so much against the big software companies though (although that's still up there), but the Australian government.

Senator Conroy has been banging on about introducing an internet filter for years now. I won't go into detail. If you're reading this blog, then it's a safe bet that you already know all about it. There are a lot of arguments against the filter, but they all revolve around one main tenet: freedom.

Which is where the EFA comes into it. They've really gotten onto the bandwagon, and have been perhaps the single most outspoken group against the filter (with the possible exception of Mark Newton). They have provided information for both the informed and uninformed public; organised and undertaken online and other forms of protest; collected, collated, and reported statistics and data; arranged means for interested groups to get together, talk, plan, and rant. And they've created 'campaigns' around the filter to both raise awareness of the issues, and inform the public on methods to avoid the filter becoming law. I've loved every minute of it.

But, for the first time ever, EFA has struck a sour note with me. And I'm not alone in feeling a little cheesed off, either. It's about the EFA's latest campaign, which has been dubbed the "Time to tell Mum" campaign. The basic premise is a comedy sketch featuring Akmal Saleh (who I've never liked all that much, mostly because he only seems to have one joke that he uses over and over again. But that's neither here nor there). Akmal, in his vaguely humorous way, tells us that we need to tell our Mums about the internet filter. This is because Mum's "love gossip" and "care about their families". He never really gives a good reason for this directly, but EFA themselves note that "[EFA] hope this campaign will reach some new people, and further highlight the myths about Conroy's Filter".

As with most things, the comments fall into two broad camps: Those who find the campaign sexist, and those that think that anyone opposing the filter is good people, and the feminists should just get over it already.

Do you want to know a secret? I'm not in either camp. I can see the issue with the sexist language. I can see how it enforces gender stereotypes, and how it is really just not helping. Hey, I'm a feminist from way back, and I'd be lying if I said I couldn't see that side of the argument with extreme clarity. I also, for what it's worth, completely support anyone who has the guts to stand up and yell about it. I strongly suggest you read "Goodbye Electronic Frontiers Australia" over at the Witty Title Pending blog for a great review of the feminist issues that have come up.

But, I can also see this from EFA's perspective. I can appreciate that they are trying to target a wider audience, an audience of people who care about their children and their families, and who are going to spread the word among the traditionally conservative-voting older generation. But it was disingenuous of EFA to target "Mums" specifically, when what they really mean is "older people who are less tech-savvy and interested in 'family' issues". But then, worse crimes have been committed in the quest for a catchy soundbite, I guess.

Therein lies the rub, then. EFA have fallen afoul of their privilege, like so many men before them (the EFA board is made up of all men and one woman. The executive is completely male. I'm not certain of racial background, and so won't make comment on that matter). They have played into gender and social stereotypes. But they're not the first. They certainly won't be the last.

EFA have made comment on how successful the campaign has been. It's gotten people talking, it has (by their own account) gotten the word out to people (Just Mums? Or others as well?) who didn't otherwise know about it. It generated some controversy and got people blogging about it, talking about it, discussing it. Those who liked it shared it around because it was funny (to them). Those who didn't, shared it around to show people how outraged they were.

Privilege is a queer beast. If you have it, you can't see it, and are almost completely unable to understand it. If you don't have it, it stares you in the face everywhere you turn. We all have privilege in one form or another. I'm female, but I have privilege in terms of being white, wealthy (in world terms, anyway), employed, educated, and in my 20's (for a little while longer, anyway). This makes it hard for me to see some things to which my privilege blinds me, but makes me very aware of those places where I'm under-privileged. EFA and their ad company FNUKY really just acted within stereotypes and privileges that they probably don't even recognise they have. They have created an ad that they - within their privilege - saw as amusing and fresh. They imagined that using a comedian and a few gags about Mums and gossip and how they care about their families but know nothing about technology would hold the public's interest, get the message across, and hopefully go viral. And, to their credit, the grand majority of the population (recalling that even though 51% of the world's population possess a vagina does not automatically make 51% of the population feminists) agreed with them. That makes for one successful marketing campaign.

Advertising uses all sorts of social, sexual, and racial stereotypes to get the message across. The very fact that marketing uses 'target groups' (read: "stereotypes") to create campaigns shows this. Take a look at Sociological Images one day to get a glimpse into how advertising campaigns are created and digested by the consuming public. You'll never look at a billboard the same way again. And while past practise does not make this particular wrong right, it does make it difficult to get very worked up over it, from my perspective anyway. The ad agency were doing what ad agencies do: create ads that appeal to a mass market. EFA were not evil by signing off on it, they were just blinded by privilege and unable to see how the campaign would play off amongst a minority of that market. The offense in this case, then, is not within EFA alone, but in the entire marketing and advertising machine, and in society that continues to mindlessly consume what that machine serves up to them.

For all intents and purposes, EFA would be best to make a proper apology (not a fauxpology like the one they have already given), and promise to do better next time. (For more information on what constitutes 'good' and 'bad' apologies, check out the Geek Feminism Wiki article on the subject). They won't, though, for a number of reasons. First, because they are still sitting in their little bubble of privilege and don't understand the issues the feminist left have taken with the campaign. Secondly, because the old marketing adage still holds true, especially on the internet: "All publicity is good publicity".

There's more to social media than Facebook

I quit Facebook on the weekend. For real. For good. And you know what?

Nothing happened.

Well, Facebook gave me a guilt-trip, but other than that, nothing happened.

No one called me in a panic, asking where I was, and what I was doing.
I didn't get an email pleading for me to come back to Facebook, and help them find red gems, or a lost cow, or a home for some virtual furry pet.
I didn't have a notice breathlessly exclaiming that someone had tagged me in a photo, or in a post.
No one sent me a message about all my friends who were having birthdays this week, or who had just 'changed their relationship status', or who were feeling lonely and unloved and needed me to 'reconnect with them'.

Instead, I went outside for a while. I read a book. And then I came back inside and updated my Twitter account instead.

You see, there's a lot of self-proclaimed "Social Media Douchebags Experts" out there, and they're all in a lather about Facebook, and telling you how to set up a fan page, and put a 'like' button on your blog and all that. Most of them know Twitter exists as well, but many of them downplay it. It's not the latest big thing right now.

Unfortunately for the so-called "experts", they've found themselves behind the eight-ball again. What is the next big thing is quitting Facebook. All the cool kids are doing it, as the rash of stories from Crikey (and Gizmodo), Wired, Boing Boing, TechCrunch, Read Write Web, and the the EFF would indicate. And they're just the ones I've come across myself.

Mark Zuckerberg, once the poster child of the Social Media Billionaire's club (the generation that came after the dotcom kids), is learning something that every Web 2.0 entrepreneur must learn. When you give something to the public that they want, they'll embrace it. But start taking too much from them, and they'll drop you faster than you can say "Where's the delete button?".

What this all means is that there's a huge amount of commentary around now, ranging from "what does a perfect social network look like?" to "I want to quit Facebook, but I don't know what to do with myself now". Well, there's some simple answers. First of all, a better Facebook will come along (and the smart money is on these guys if you ask me. You heard it here first). Secondly, you don't need to wait for the next Big New Shiny Thing to take off. Go sign up at any of the squillion or more other social media sites, and work out what else is out there. There's more to social media than Facebook. Get out of your comfort zone, and explore.

Lest We Forget ... But who have we already forgotten?

As ANZAC day approaches, and my bugling duties are again requested, I thought it would be apt to draw attention to the post I wrote on the topic this time last year. The last paragraph mentions this:

This ANZAC day I'd like to remind you all to think about not just the white Australians (and all the members of other nationalities) that have died during war, but to remember the original owners of this land who died in other, non-glorified, and unremembered battles.

When you stand up and say "Lest we forget" this ANZAC day, please think of those who history has already forgotten. There were around 500 Australian Aboriginals and Torres Straight Islanders who served in World War I, and around 5,000 serving in World War II. Aboriginal and Islander men and women have served in every major conflict that Australia has ever been involved in. Many of them never came home.

Those who did return were refused pensions, land grants, and other benefits offered to white servicemen, and were barred from entry into the Returned Serviceman's League (RSL). They were denied the recognition, honour, and respect that their mates in the trenches received. And now, over sixty years since the end of World War II, we are still refusing to give them that honour.

This ANZAC day, spend two minutes in silence for those who history have forgotten, Lest We Forget also. If you are in Canberra, please consider attending the the Aboriginal and Torres Strait Islander commemorative ceremony after the dawn service at the War Memorial.

-=oOo=-

The information for this post was drawn mostly from The Anzac Day legend & Coloured Digger Anzac march


The image is part of the The Coloured Digger set, uploaded to flickr by Findo and is shared under a Creative Commons Licence. 


Information about the various services (including the Aboriginal and Torres Straight Islander commemorative ceremony) can be found on the Australian War Memorial website. 


The AWM website does not include directions to the Aboriginal Memorial Plaque. Directions can be found here, or on the The Anzac Day legend & Coloured Digger Anzac march.


I won't make comment on how far removed the plaque is from the memorial itself. I'll allow these links to speak to that.

-=oOo=-

Lest We Forget.

FOSS Training

I was privileged enough to be able to attend linux.conf.au in Wellington in January. While there, I caught Bob Edwards' and Andrew Tridgell's talk on "Teaching FOSS at Universities" (video of which can be found here). It intrigued me.

Open source software development is very different to developing software in a more traditional, closed source environment. The aim of the course is to teach students how to go about working within the open source community. It covers the practical aspects of checking out code from a repository, submitting patches, and undergoing code approvals and reviews. It also looks at some of the less tangible aspects, like what's accepted and expected within the community, the motivation behind project development, and governance. The course also goes into some detail about documentation.

Documentation for open source projects is not quite the known quantity that it can be in many proprietary software environments. I once had a developer I was working with describe it as "we live in the Wild West out here", and - at least to an extent - he makes a good point. While writing for an open source project may not be as wild and exciting as that sentence makes it sound, it can sometimes be unpredictable and, at times, incredibly frustrating. Frequently, a book has been written and reviewed in preparation for a release, only to find at the last minute that a feature has been pulled from the version, a component has suddenly been renamed, or the graphical interface has had some kind of redesign. All of these things happen to open source writers on a regular basis, and frequently the only solution is to pull an all-nighter, get the changes in, and have the document released on schedule. And that's only if you were lucky enough to find out about the change with enough time to spare before release!

So how does a writer plan for and write a documentation suite when there's so much unknown in a project? The answer is - perhaps ironically - to plan ahead. You can't plan for every contingency, nor should you. But if you have a plan of any description, you're going to be better off when things start to go wrong. Pin down the details as best you can as far ahead as possible. But don't leave it there, continue to review and adapt your plan. Keep your ear to the ground, and constantly tweak your schedule and your book to suit. If something comes up in a mailing list about a feature you've never heard of, don't be afraid to ask the question - "Does this need to be documented? Will it be in the next version? Where can I get more source information?". Another trick is to make sure you build in 'wiggle room' to your schedule, in case you suddenly discover a new chapter that needs adding, or a whole section that needs to be changed. If you're consistently a few days or a week ahead of schedule, then even a substantial change should not throw you too far off balance.

Just like a ballet dancer, technical writers need to be disciplined, structured, and organised. But you also need to have grace, poise, tact, and - most importantly - flexibility.

Thanks to Bob and Tridge, I'll be lecturing the 2010 FOSS course students at the Australian National University later this week. I'll also be contributing the textbook that is being developed for the course. True to form, it is being built by and for the open source community, using open source tools (including Publican which has been developed in-house by some of my esteemed colleagues). Watch this space for more information.

Cross-posted to FOSS Docs