On Writing, Tech, and Other Loquacities

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


3 Comments

The Grass is Greener on The Open Side

The Grass is Greener on the Open Side

Now, I know what you’re thinking. You’re thinking, “Oh my, here we go again. Another open source advocate banging on about freedom”. Well, yeah, I have to admit to at least a little bit of truth in that. Open source advocates do like to talk about morals, and they do like to say things about open source being ‘good for society’ and how it’s the ‘way of the future’. Most of all, though, open source advocates like to bang on a lot about ‘freedom’. But I’m not your average open source advocate. Every tech writer has their favourite program to use, and in many cases you don’t get a choice about which one that is. I’m not going to tell you that you shouldn’t be using those programs, and I’m not going to tell you to go to your boss and tell them that you’re not going to be using those freedom-hating platforms any more. It’s just not practical. I will tell you to use whatever works for you. If there is a program that you use that ticks all your boxes – that does absolutely everything you need it to do, then by all means go ahead and use it. All I want you to do is to be aware of the alternatives, and to understand the differences between them. That way, you’re making an informed choice about the software you use, and the way you interact with technology.

Freedom, and how it relates to beer

So, I said I wasn’t going to bang on about freedom, but I do need to mention it, if only to straighten out some of the terms I’ll be using. Freedom gets mentioned a lot when discussing open source software, and thanks to Wikileaks there are a lot of nonsense phrases doing the rounds right now like “information wants to be free”. I would like to explain what we actually mean when we talk about open source software being ‘free’. As I’m sure you’re all painfully aware, English can be a bit confusing sometimes, and we quite frequently come across words that have two or three different meanings, depending on the context it’s used in. The English word ‘free’ is a perfect example. We can steal two words from the Romance languages to describe the different ways we use ‘free’ in English. First of all, a word I’m sure you all know and love, is ‘gratis’. The word ‘gratis’ means free of charge, or without cost. The other word is ‘libre’ which means the state of being free, or of having liberty. There’s a much easier way to illustrate this concept though.

We all know that the best beer is the beer you don’t have to pay for. That is, it’s beer that is ‘gratis’, or free of charge. We can refer to software as being ‘free as in beer’ when we mean that it doesn’t cost any money to use. This is the type of ‘free’ that is being used when we discuss freeware, which you’ve probably all come across before. Freeware is free as in beer, but it has its catch: you still need to read and agree to the end user license agreement in order to use it, and you won’t be allowed to change the way the program works, or create any add-ons or extras, such as documentation or translations. In many cases, freeware can only be installed on personal networks, not business ones, and there are quite often restrictions on how easy it is to share the program too.

When we talk about the ‘libre’ sense of free, we say ‘free as in freedom’ or ‘free as in speech’. Essentially, when we talk about freedom with open source software, this is the freedom we mean. It’s the freedom to see the nuts and bolts of the software you’re using, the freedom to make changes and share them with your friends, the freedom to take the code and use it in your own project, and the freedom to suggest and submit changes to the code itself, or the stuff that wraps around the program, like the documentation. It is also possible to have software that is free as in freedom, but isn’t free as in beer, too.

Have you got a licence for that thing?

So before we move on there’s one other term I’d like to straighten out: pirates. My entire network at home was set up using free software – that’s free as in beer, it didn’t cost me a cent. However, I’m not a pirate (and that’s not just because I don’t have a wooden leg and a parrot). Every piece of software I use in my home network is open source and was obtained perfectly legally.

This is because the free-as-in-freedom and the free-as-in-beer is written into the license agreement for the software I use. You’re probably familiar with the End User License Agreement (EULA). That’s the bit that you have to agree to when you install closed-source software. It’s usually a big long chunk of text, all written in legalese, and we all ignore it and hit “I agree” to continue. Open source software doesn’t use a EULA, but it does have a license. The license works in more or less the same way as a EULA, except instead of saying “You may not sell, license or distribute copies of the software” it says something more like “you can use this software free of charge, as long as you keep it that way”. In other words, if I wanted to pay for it, or I wanted to sell it to my friends, I would be breaking the agreement, in the same way that giving away copies of Microsoft Office for free would be breaking the EULA. There are lots of different open source licenses, but they all work in much the same way, with only minor differences between them. The main one is the GNU General Public License, which is referred to as the GPL. The main restriction on the GPL is that whatever you do with the code, it needs to include a copy of the GPL with it. And that’s really as scary as it gets. I could go on at length about licensing, but there’s probably another whole article in there, so let’s move along.

Decision time!

Consider you’re in the market for a new bit of software. Often your purchase decision will come down to features, and if one option has the features you need and the other one doesn’t, then by all means go ahead and install the software that has all the bells and whistles you require. Provided you agree to the terms of the license or the EULA, and you pay whatever is requested, then there’s no problem. But what about when the features are equal, and the differences come down to licenses and cost? Most of the big name software will cost you money in some form or another for the full version. After you’ve paid your money the product is yours though, right? Wrong. The software company can decide to change the software whenever they want. You would have all seen this happen on your Windows machines. You agreed to a EULA when you installed it, but Windows gets new updates every other day. Got any idea what’s in those updates? No, nor do most people. We need to trust that the big software companies are going to do right by us, and in most cases that’s not difficult to do. They’re big companies with millions of users, and if they tried anything nasty, we’d probably know about it. So that’s a risk most of us are perfectly willing to take.

>So you’ve paid your money, you’ve got your software, and you’ve been happily working away with it for a while. Then someone sends you a file that you can’t open, because it was created with a newer version of the software. All of a sudden, you realise that your old version doesn’t have the features that the new version has got. So what do you do? You have to upgrade. Which costs more again. Once again, you click through the EULA, agree to it, pay your money, and you’re off again. You’re probably very familiar with this process.

Now, what happens if you don’t like something about the program, or if you discover a bug in the program – something that doesn’t work properly? For the most part, you probably shrug it off. There’s not much you can do about it. What about the documentation? We’ve all come across laughably bad documentation, hopefully you weren’t the author of too much of it. What happens when the documentation for your piece of software doesn’t describe things properly? Or doesn’t include information you need? Have you ever thought “Gee, I could write that so much better”. If you’re multi-lingual, have you ever wished that a company would provide documentation in a different language? Have you ever wanted to create a guide that covers a situation you use every day, and you think others would find it useful too? You can’t do any of that stuff with closed source software, because the EULA specifically forbids it. The only way to be able to make those changes would be to go and get a job at Adobe or Microsoft. And while I’m sure we’d all love to land a position like that, unfortunately for most of us it’s not horribly likely.

So let’s look at the alternative. Most open source software will cost you nothing, it’s free as in beer as well as free as in freedom. You would go to the website, pick the version you want, and you’re off. If you need help, you can check out the embedded help, or the official documentation on the site, just like with any other program. And if you don’t like either of those options, there are heaps of other places to get help: wikis, forums, chat channels, numerous blogs and websites. You could also go to an open-source manual website, like flossmanuals.net and find out if someone else has written a full guide. And what about problems or bugs? The first thing to do is to search the web, it’s possible that someone else has come across the issue and has already found a solution. If not, then get in contact with the developers – all open source projects will have a number of ways to do this – and let them know about it. They’ll probably ask you for some more details about the problem so that they can get it fixed, and then they’ll go right ahead and fix it for you.

The other fun part is if you think you have something to add. If you’re a programmer, and you’d like to write a new feature, or fix a bug, you can do that. If you’re a writer, and you want to improve the documentation, or you want to do a translation, then you can do that too. In those cases, you will usually be welcomed with open arms and given everything you need to get started. And that’s because open source software is not developed by a group of paid engineers in an office block, but by people like you and me. It’s created by a community, and anyone who wants to be a part of that community and work to improving the software they’re using will always be welcome. Of course, you don’t have to contribute to a project, though, if you don’t want to. You can also just download and use it, just as you would with any other software.

Arguments, naturally

Of course there are arguments both for and against open and closed-source software. Most of them on both sides are reasonably valid. One of the main ones is that closed source stuff is usually more stable than open source, because they have a room full of developers who are paid to fix bugs and write features. This is interesting, because in some cases it’s true. But to be a fair comparison, you can’t really compare the stability of Word against the stability of a project that was created by two guys in their garage for their three friends to use. If you want to compare them fairly, compare the stability of Microsoft Word to the stability of Open Office, which is an open source project by Oracle and is supported by IBM, amongst others, and has been around for over 10 years. Neither of these projects are likely to go away any time soon. The other side of the coin is the little software development groups. Anyone can produce software and sell it, and if those little shops go bust you end up with an unsupported product. That doesn’t change whether it’s open or closed source. The difference is that with open source, because the code is available to anyone who wants to look at it, there’s at least a chance that someone at some point will pick up the code and have another bash at it. That’s never going to happen with closed source projects, simply because the licensing doesn’t allow it to happen.

I’m still not sold

The good news is that you don’t need to be totally sold on either open or closed source software. You don’t have to go totally one way or the other. Because open source software is free to use, and easy to get, you can go ahead and download any number of programs, just to see if you like them. And if you feel like making a contribution to the program, or joining the community around your favourite program, then go ahead and do that too. The great part is that you can install and use open source software anywhere you want, and use closed source software in exactly the same way. They will happily co-exist on the same system.

It’s not just about the freedom

I said right at the beginning that a lot of open source advocates bang on a lot about freedom, and I guess that in a lot of ways they’re right. Freedom really is a big part of open source, and explains a lot of why it’s awesome. But I think there’s something more to it. It’s not just about the freedom, it has a lot more to do with the community. Whenever you get group of people together with a common goal in mind, they can achieve just about anything. When the goal of that group is freedom, then I think that the world can really only become a better place because of it.

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

This article was originally a web seminar for the Society of Technical Communicators. Since then, I have also presented it for the Canberra Society of Editors. It was longer as a speech, but had fewer funny bits.

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

A shortened version of this article was published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 2: May 2011

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

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