On Writing, Tech, and Other Loquacities

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

Leave a comment

linux.conf.au 2015 – Documentation Miniconf

Day 1 is drawing to a close at linux.conf.au 2015 and we’ve just wrapped the documentation miniconf. There was an interesting mix of talks today, and as the first documentation miniconf at an LCA, it’s given me some great ideas for growing the miniconf in future years.

As for me, after doing the Agile Documentation Lego talk at LCA in Perth in 2014, I felt I needed to give a good follow up show, this time focusing on Every Page is Page One. To do this, I devised a game based on the children’s book “We’re Going on a Bear Hunt”, and using Play-Doh to make it a little more hands on.

2015-01-11 (1)


Leave a comment

Linux.conf.au 2014 – Perth, WA

Possibly my favourite conference, linux.conf.au is coming to sunny Perth in January 2014. I’ll be returning to the Haecksen miniconf driver’s seat (check out haecksen.net for more info and the Call for Proposals), and also will be giving a talk myself, called There and Back Again: An Unexpected Journey in Agile Documentation. This is a talk I’ve given a few times already, including at OSDC 2013, so I’m really looking forward to sharing it with the linux.conf.au audience. That, and I’ve never been to Perth before, so yay!

linux.conf.au 2014 - Perth WA


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.


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 …


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.


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.


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.


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:


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.


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 …


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.


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.


Leave a comment

The Mechanical Turk and OSDC

OSDC 2011 kicked off today at the ANU. I tripped along to the OSIA (Open Source Industry Australia) miniconf, which Red Hat sponsored, and was mightily pleased to hear Stuart Gutherie reference one of my favourite pieces of historical weirdness: the mechanical turk. I couldn’t help but hold forth, and eventually gave an impromptu lightning talk on the subject.

The mechanical turk existed in the late 1700’s, and was billed as an “automaton chess player”. In reality, it was a wooden box in which an accomplished chess player could sit and manipulate the chess board on top, while a wooden “turk” would appear to move the pieces mechanically. It was invented by Wolfgang von Kempelen, a Hungarian, who also invented a “speaking machine”, a speech synthesiser, which was actually quite important to the early development of phonetics as an area of study, but not half as famous as his great hoax, the mechanical turk.

What makes the mechanical turk so interesting is the lengths von Kempelen went to to persuade his audience that the turk was, indeed, an automaton. He would show the audience first one empty cabinet, then another, and then in the third cabinet would be a complicated looking system of levers and pulleys. The cabinet was designed that, throughout this proceeding, the human operator could easily slip from one side to the other on a sliding seat to hide from view.

The trick was not exposed until the mid-1820’s, despite some very public appearances. The mechanical turk won chess games against such prominent figures as Napoleon Bonaparte and Benjamin Franklin before being found out, although no one has recorded the names of those chess players working the turk from underneath.

How this becomes relevant to the IT industry is equally as fascinating as the history of the machine. In the days of the turk, playing chess was something that no machine was capable of doing. It required a level of computation that only humans were capable of achieving. We have now invented computers that can play chess (and even appear on game shows) with ease, but there are still tasks that we can’t replace with a small shell script. Many of these tasks are frustratingly simple, but require a human brain to parse the data. Writing tasks often fit into this category: things like writing short captions for images, changing the style used in a document, or changing text from British English to American English spelling.

Within Red Hat, we spend a lot of our time working on errata text. After a program has been released it is fairly normal to find bugs. When the developers go through and fix a bunch of those bugs, they will send out an update termed an “errata release”. For each bug fixed, the technical writers need to document it, which means writing four sentences: one sentence each about the cause of the bug, the consequence of the bug, the fix that was applied, and the result of the fix. This is, naturally, quite tedious and boring. It’s natural for us to want to automate this process, but unfortunately it’s a job that requires a human brain.

So we did the next best thing: we created a mechanical turk. We call it “The Turkinator”, and it’s currently available for Fedora errata releases. Basically, you choose whether you want to write a Cause, a Consequence, a Fix, or a Result; you’re given a bug to read; you submit your sentence and that’s it. In this way, we automate the task of writing errata text by breaking the big task down into little tiny pieces and asking humans to perform the work of a shell script.

This model has an extra added bonus in the open source space, though, and that is what we like to call “micro-contributions”. Anyone who has contributed — or thought about contributing — to an open source project would understand how daunting that first contribution can be. By creating the possibility of micro-contributions, potential contributors can have their first (and second, and third …) patch completed in under a minute. Instant contributors for the project, and instant contributions for the development team.


1 Comment

linux.conf.au 2012 Call for presentations!

linux.conf.au is the biggest Linux and open source conference in the southern hemisphere, and rightfully so! I was a speaker at the conference last year in Brisbane (the video is on my videos page) and had a great time.

This year it’s being held in Ballarat, Victoria, and I must say I’m quite looking forward to finding out what a regional LCA is like. Anyway, the CFP is open, I’ll be submitting again, and I suggest you do too. More details on the LCA website.


1 Comment

Open Source Documentation in Four Easy Steps (and one slightly more difficult one)

At Red Hat, we have a content services department that is about sixty people strong. Even though the department is pretty big these days, back when I started with the company, we were still trying to work out the best way to run a successful enterprise-level documentation team. What that means is that I have been involved in some of the big discussions that we have had over time about what processes we needed to get in place in order to allow us to produce the massive amounts of documentation we required as our product offerings grew. As a department, we grew very big, very fast, and our processes needed to be flexible enough to accommodate the large number of new hires we had, and still have, coming in, but robust enough to be valuable and reliable. They also need to fit in well with the engineering practices in place in the company, and the tools that our development teams use and are familiar with. Of course the other really important factor was that we had to be open. We wanted to use completely open tools to produce our docs, but we also needed to be able to work with community teams, such as the Fedora group.

Like many documentation groups, at Red Hat we use a five-phase waterfall model to produce documentation. It’s based on the ever-popular JoAnn Hackos method: starting with planning, the content specification, then writing and editing, translation and production, and then a retrospective review. At Red Hat at the moment we’re at a place where our development teams are increasingly using Agile-style development models to produce software, and that means the pressure has been on us to develop in a less rigid way than the old waterfall model has been allowing us to do. Also, it’s no secret that the online world is changing, and people now expect to be able to interact with information at a much deeper level than ever before. They don’t want to be presented with static, hard-copy books any more. They want dynamic, interactive, usable, and above all useful documentation.

In order to be able to work out what kind of model we needed to use, we needed to go back to basics. All technology is about solving problems. Back when we were sitting around in caves, we had a problem: there was all this food running around outside, but we didn’t have a way to get it to stop running around, so we invented a club and solved the problem. Since then, we’ve used technology to solve all sorts of problems: horses were sometimes problematic to control, and they didn’t go very fast, so we invented cars. The hard wheels used on early cars weren’t very comfortable, and when they broke they really broke, so we invented pneumatic tyres. We also had problems being able to see in the dark so we invented electric light, being able to go to the toilet when it was raining or cold so we invented indoor plumbing, being able to send messages to people on the other side of the country so we invented the telephone, or on the other side of the world so we invented email.

Even these really technological things that we find ourselves documenting now, are all solutions to problems. One of the first things you need to be aware of when you’re writing documentation is what problem your users have. If you can’t describe the problem in one or two sentences, then you don’t understand it well enough, and you need to keep researching. Because if you keep going, all you’re going to end up with is hollow marketing spin. That’s how we end up with documentation that talks about “leveraging synergies”: words that sound great, but have no meaning.

So at Red Hat we came up with a fairly simple model, and that is that documentation needs to be able to be boiled down to three things:

  • Describing the problem
  • Solving the problem
  • Giving any additional information

Anyone who has done any work with DITA would understand that what I’m really talking about here is:

  • Concept
  • Task
  • Reference


So we’ve more or less said that DITA is where we need to go next. But we didn’t want to completely restructure the tools we were using. We have a fairly large people investment in our tools. The main tool we use is Publican, which was developed by an engineer in our Brisbane office. It uses Docbook XML and gives us a command line interface that we can use to create new blank books, apply corporate formatting, and it integrates into our internal packaging system so we can create all these different formats for our books – HTML, PDF, and ePUB on the website, and we can also create RPM packages and man pages to package in with software. We combine Publican with SVN to give us a complete CMS, in short.

We looked at DITA and DITA-OT, the DITA Open Toolkit. We realized two things: first of all, it would take a significant amount of work for us to bring an open DITA toolchain to the level of maturity and system integration of our existing Docbook toolchain. Secondly, we wouldn’t get the really significant benefits of topic-based authoring without a Component Content Management System – a CMS that manages content at a very granular level. Putting those two things together made it clear that if we changed to DITA all in one hit, it would take us significant time and energy just to get back to where we already were with a mature open source complete tool chain. So we decided to take an evolutionary, rather than revolutionary approach. It’s a much more open source approach: to re-purpose something that you already have, add a script here, a small command-line tool there, release early, release often, and let the user community guide the development, rather than trying to design and implement some grand system in a distant (and expensive) future.

What we needed was something that worked in a similar manner to DITA, gave us content re-use and all that good stuff, but that would work with our existing Docbook XML and Publican tools. The first thing we did was to start creating topics in Docbook, using Docbook syntax, and a command line tool that we called the “Topic Tool”. This was a really simple command line tool that allowed us to write XML snippets (or ‘topics’), and save them in SVN. We used an extensible template model, where the topic tool retrieves a Docbook template from a central repository to match the topic type you specify. That way we can create new topic types, and even modify the Docbook syntax of existing topic types, without changing the tool on users’ machines. That was an important decision, and a major part of the evolutionary “Release, Review, Refine” approach we wanted to use. Over time we did change the Docbook syntax of the basic topic types and create new topic types, validating the open source maxim “plan to throw the first one away”.

The basic workflow with the Topic Tool is like this: you tell the tool which topic type you want, and it will then download the template and prefill some information for you. You can then edit the topic in a text editor, and import it back into the repository. It’s then possible to view your topic from the repo directly, which means anyone can now see it and use it. We then include those snippets into any book you want using an xi:include, build the book as normal with Publican, and voila! we have a book with content reuse. So that was pretty awesome, and if you read any of our Virtualisation documentation you’ll probably not know it, but that’s all based on topics and maintained using the topic tool.

Of course, once we got to about 300 topics in the topic tool, we started to notice that we have another problem, we were having trouble locating topics within the repository. This made us realise that what we needed was a better way to organise it all, so we wrapped a neat interface around Topic Tool using Open Grok. OpenGrok is designed for software engineers to search source code repositories, so it worked well for what we were trying to do. This is where the open source ecosystem came into its own all over again – there are a million off-the-shelf components and projects that you can choose from to build your own system. In the end we had a web-based search tool that was pretty basic, but did the job.

Content reuse is an obvious application of topic-based authoring, but by this stage, we’d started to realise something even more exciting. Our definition of a topic is a unit of information with a single subject – that means that it talks about one thing, and one thing only – and that has a single information role: that is, it’s a concept, a task, or a reference. If we gave three topics – a concept, a task, and a reference – to a robot, along with a rule describing the “explain, answer, extra info” pattern, and some kind of graphical template, that robot can assemble those topics into meaningful and useful output for an end user. What we wanted to do was to automate this process.

When humans assemble content into a book, they are making decisions. What aspects of the information are their decisions based on, and what rules are they consciously or unconsciously using? That was what we wanted to create: A system that would allow us to store metadata about a topic, and use rules to automate assembly on a scale that we just couldn’t do by hand-coding.

So we developed a system that we call Skynet, which allows us to dynamically sort and locate topics. Select the topics you want, and Skynet will download the code that presents those topics in a consumable way. Of course, we started dreaming big after all this. We’ve started thinking about moving away from the documentation-as-a-book paradigm, and started considering “Documentation 2.0”. Why not include comment fields on our documentation, that will allow our reviewers – quality engineers, subject matter experts, editors, and the like to make comments directly in the book rather than creating a separate list? And why not offer that functionality to our users as well? What if we had the equivalent of a Facebook ‘like’ button? Users could ‘like’ sections that they found useful, or leave comments saying “when I tried to follow these instructions, X happened” or “this seems to be missing a step” or the like. If we break away from the book model, we start to be able to think about documentation as something that our users can interac with. We could have popular topics bubble up to the top of a list, or divide books into audiences, and present the information for each audience differently, giving them a tab to click to see the information in various ways. We could implement something similar to the Amazon “customers who bought this also bought this” and present similar topics to our readers. Using single-sourced content, and content reuse, through a system like Skynet, is going to allow us to move into these more innovative delivery methods.

The team working on the Skynet project have 110% discoverability as one of their goals, to quote the team leader: “the documentation finds you”. In other words, when you’re working on something, and you get stuck, the documentation is there at a click or a glance, ready for you to interact with it. Of course, I’m sure some of you are saying “Help” right now, and yes, I agree with you. That is something else we’re talking about, and something that Skynet will enable us to do. Skynet pushes out XML now, and of course there’s plenty we can do with that as it is, but we can also extend it to push out all manner of things, including Mallard for Gnome Help.

So let’s take this conversation back to processes. All this dreaming is fantastic, but at some point we still have to actually do the hard work. Without a solid process, and a great set of standards, we’re not going to be able to get there. We’re doing a lot of internal testing, and we’re dipping our toes in the water with the topic tool and with Skynet. So far, we’ve been able to slip these in to our existing standards, but that’s not going to last for long. With a paradigm shift as big as this, everything is going to have to change, and that includes the way we go about producing our documentation. We need to be organised, we need to make sure what we do is repeatable, and we need to maintain our high standards of quality and accuracy in our documentation. Most of all, though, we need to maintain and even increase our focus on the customer. These changes come about not because we got bored with doing things the old way, but because we believe it’s a better way to serve our audience. Never, ever forget who you’re writing for, it’s those poor sods out there with their problems that they’re trying to solve. Our goal is to give them the tools they need to solve them.

So, to recap:

One of the main things that we have learned is that process is king. If you don’t have a solid process for producing documentation, then you’re going to find yourself floundering at every point along the way. You’re going to end up with documentation that doesn’t cover what it needs to cover, isn’t accurate or well-written, and doesn’t get out on time. Without a plan for how you’re going to tackle the project from end to end, then you’re not going to succeed. It’s that simple.

The second thing is about tools. You need to decide ahead of time what tools you are going to need during the project, and make sure you have them ready and up and running before you start. It’s horrible to get halfway through writing and find out that one of your writers doesn’t understand how to use a semi-colon. It’s even worse if you get halfway through and realise that one of your writers doesn’t understand Docbook XML, or whatever authoring tool you’re using.

While we’re talking about tools, it’s important to keep it open everywhere you can. This can seem counter-intuitive to those of you who have worked in big companies, but being open doesn’t mean giving away business secrets, or exposing your competitive advantage. I think Red Hat of all companies really proves that the openness can co-exist with secure business practices.

Part of keeping it open is about keeping it real. The people behind your processes, the people doing the actual work day in and day out: they’re real people. They’re real people, with real lives, and real families. You need to be able to work with people, and ensure that the loss of one person isn’t going to make the whole project tumble. The other thing you need to remember is that your readers are real people as well, you need to make sure that you’re giving your readers something useful, and something that they will get value out of.

And finally, I want to remind you about reviews. We all understand the importance of reviewing our writing for correctness, and reviewing our projects to make sure we can learn from our mistakes. You need to extend reviews to the documentation process itself, as well. Never be afraid to change things around. Just because it worked last time doesn’t mean it’s going to work next time. And just because it’s worked in the past, doesn’t mean it’s the best way to do it in the future.

This post was originally a talk given at the Open Help Conference in Cincinnati Ohio, on 5 June 2011.

The slide deck is available on Slideshare: Open Source Documentation in Four Easy Steps (and one slightly more difficult one)

You can also download this article as a PDF file: FourEasySteps


Leave a comment

Sssh! Sneak Preview!

Don’t tell anyone I told you, but here’s my slide deck for the presentation I’m giving in Cincinnati this weekend at the Open Help Conference

Not sure if there’ll be recording on the day or not, but I’ll get some more details up here afterwards, either in the form of video or an article.

See you soon, America!


Leave a comment

Open Source Developer’s Conference 2011 – Call for Papers!

The Open Source Developer’s Conference (OSDC to its friends) is being held in Canberra in November this year, which is a little bit exciting, and they have just opened their call for papers.

Also this year, for the first time, they’re asking for miniconf proposals too. I would love to do a whole miniconf on open source documentation, but I’m not sure I have that kind of stamina. Of course, If you’re interested in helping me out, let me know!

I spoke at OSDC last year, when it was in Melbourne, and the footage is on my videos page. I thoroughly enjoyed the experience, so it will be interesting to see what kind of event Canberra can put on this year.



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



Leave a comment

Taking a Walk on the Open Side

Tonight, I gave a talk about Open Source for the Canberra Society of Editors (who invite the ACT branch of the Society of Technical Communicators, of which I am a member). There was a reasonable crowd, who all seemed interested and who asked lots of questions. It is always satisfying to give a talk and to see a light go on in people’s eyes, see that spark of something flash in their faces as they learn something new, think about something in a different way, or experience a different perspective. That, my friends, is what makes it all worth it.

This talk wasn’t recorded, unfortunately, so I won’t be providing video, but I can tempt you with my slide deck. Unfortunately, my slide decks don’t tend to have many words on them, so you might not learn much, but there are lots of pretty pictures. And if you were present at the discussion tonight, thanks for coming, and I hope you found some inspiration. Please feel free to drop a note in the comments if you’re after more information about anything.

If you do want to know more, there is a fairly severely shortened version of it in this month’s edition of Words. I’ll put the full text of that up here in the next few days, or you could head over to their website and check it out there.