On Writing, Tech, and Other Loquacities

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


Leave a comment

Birthdays, and Other Silliness

I woke up on the morning of my birthday to this, at the top of our team wiki page:

Lana_birthday

Admittedly, this isn’t the silliest thing we’ve had at the top of our wiki page recently. In fact, our manager Mikal has made it a work requirement that we create at least two new memes a day, as a team, and a script rotates them on a daily basis.

The point of mentioning this is that I wanted to talk a little about our culture. We’re a small team, and we’re the only Rackspace engineering team within Australia, which makes us fairly unique. Of the four of us, we’re scattered quite neatly along the Australian eastern seaboard, in Canberra, Adelaide, Hobart, and me in Brisbane. We’re very new as well, so for the moment we’re basically muddling our way through. However, there are grand plans, some of which don’t even include crowning Mikal as the Sarcastic God of All Pickles, as hard as that may be to believe.

The main thing we want to try and achieve, at least to begin with, is to create an identity for the group. Mikal and I have worked on this kind of thing before (albeit with a shorter lifespan), with linux.conf.au 2013. With the conference, we spent a lot of time working out what the ‘feel’ of the conference was going to be, and what our messaging around that should be, how we should convey that feeling to the audience.

My very next step in doing the same thing for the Rackspace Cloud Builders Australia group is exactly the same as we did for linux.conf.au 2013: work out the over-arching message, and then decide on ways to effectively communicate that. We need to work out how to be fun and energetic, without compromising the message that we are smart and innovative, and working hard for our customers. A brand challenge to rise to.

Have you ever crafted a similar message for a group you’ve worked on? Do you have advice for me?


Leave a comment

OpenStack Contributions

Like most people I learn best by doing, so one of the first tasks I set myself when I started working on OpenStack documentation was to get a docs patch in as quickly as possible. In the end, this turned out to be a copyedit on the introduction to the High Availability guide, and it happened on day two, right before I did my induction in Sydney on day three. I had no idea this was a big deal until I got to the Sydney office to find myself being lauded, which was somewhat amusing, and slightly embarrassing.

Stackalytics_firstcommit

So the main upside of this is that I am now officially an OpenStack ATC (active technical contributor). The next step from here is to keep making patches of course, along with code reviews and the like and hopefully to continue being useful to the community in this way.

One of the more important things about coming to a new project is working out the workflows. All the formal stuff is documented, of course, but sometimes it’s the common knowledge things that are hardest to pick up; the bits that ‘everyone knows’. I’m still feeling a little daunted by code reviews (what exactly constitutes an acceptable patch? To what extent should I be testing the proposed content?), but after discussions with the core docs contributors I’m starting to get a handle on those. This week has been spent largely as a sponge: just trying to soak everything up. After a day or two off over the weekend, hopefully my brain has made sense of most of the things I’ve learned so far, and next week will be a week of action!


Leave a comment

An exit, and an entrance

All the world’s a stage,
And all the men and women merely players:
They have their exits and their entrances;
And one man in his time plays many parts
— ‘As You Like It’, Shakespeare

It is not often that you have to make a choice between an amazing job, and another amazing job. But, after six years with Red Hat, I have decided to take up a new position with Rackspace, effective 28 October.

I have grown up with Red Hat, in particular the Australian writing team, and in many ways the person I am today has been shaped by the people and the culture here in the Brisbane office. I am sad to be leaving, but I take a little piece of that crimson fedora with me. To all my friends and colleagues at Red Hat: keep up the great work, keep innovating, and know that there are Red Hat alumni out there, cheering you on from the sidelines.

To anyone who is considering embarking on a technical writing career, or expanding their tech writing horizons, consider joining the team at Red Hat. They’re doing groundbreaking work, they’re doing it out in the open, and they’re having a huge amount of fun as they do it.

I’ll be blogging a lot more in my new role, so please stay tuned as this site gets a bit of a nip and a tuck, and before long you’ll start seeing a lot more from me.

the-weird-writer


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.

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.


Leave a comment

???????

I wrote this several years ago at this time of year, and it still feels very relevant.

Happy Diwali, everyone 🙂

————————————————————-

Today marks the start of the 8-day long diwali (or d?p?vali) festival. It is a festival of light, celebrated in Hinduism and Buddhism, among others.

Traditionally, people light candles, wear new clothes, and celebrate with sweets and snacks. What got me thinking, though, was the many and varied stories of how diwali came about, through legend and history. I won’t go into detail (if you want it, the Wikipedia page is a good place to start), but the stories are all essentially about a homecoming, a return from exile, the release of detainees.

In the past few days, I’ve been bothered by our government’s reaction to the 250 Tamil asylum-seekers, who are now on hunger strike in a boat in Merak, Java. These people are apparently so evil that both sides of politics agree that they shouldn’t be allowed in to our country, to enjoy our freedoms.

We quite happily advertise our wealth to the world. When those who have nothing; those who live daily in fear and poverty; seek to improve theirs and their childrens’ lives by giving everything they have to come here, we turn them away. We turn them away.

What evil do these people encompass? The detractors will cry that we will be over-run. Well, so what if we are? We have boundless plains to share, after all.

Even if you have never heard of diwali before, even if this day would normally have passed for you without a glimmer of recognition of what today means for so many Hindus and Buddhists, please just take a moment to think of those who will not be returning home. Take a moment to consider how many people are currently living in fear of their lives, in complete and abject poverty, and who are willing to give everything they have to try and rise above that. And think about the people who are so close to their dream of the future … yet so far.

Happy diwali. I hope that – for you – it is a time of light and happiness. And I hope that you will spare a thought and light a candle for those who cannot celebrate diwali this year, through no fault of their own.


2 Comments

Open Source Docs: the Good, the Bad, and the WTF?!

This is intended to be a bit of a light-hearted look at what can go so tragically (and sometimes hilariously) wrong with open source documentation. There is a bit of a point, though, and that is that I’d like to hopefully go through some reasons why you might need to consider having a real life tech writer work on your project, and how you can actually go about making that happen too. But first, on to the funny …

Open source documentation usually sits somewhere on a scale in between bad and awful. It’s not just open source, though. Bad documentation is everywhere. A lot of the time it’s confusing, but sometimes it can be downright dangerous.

The irony here of course is that they’re attempting to make the situation safer, but have managed to make it less safe by introducing a spelling mistake, and making the sentence so complicated that you need to read it several times before you understand what they’re trying to say. Which is different to what they’ve written. Of course, by the time you’ve read it and gotten the message, you’ve probably already driven off the road.

There are some truly wonderful writing-related quotes out there, so I thought I’d start out with this one. Some of you might have heard of this guy. His name is Jerrold David Freeman, and he uses the pen name David Gerrold. Under that name, he wrote an episode or two of a little known science-fiction show call Star Trek. David Gerrold, in turn, has his own pen name, Solomon Short, who wrote some appallingly bad fiction, apparently, but otherwise appears to be famous merely for a few pithy quotes, this being one of my personal favourites …

“I’m all in favour of keeping dangerous weapons out of the hands of fools. Let’s start with typewriters”.

Of course, the point here being that there really is some truly awful writing around, which is interesting when you consider how much of it he was responsible for.

And while we’re talking about dangerous weapons. I guess even a typewriter would be dangerous if you held it like this. But we’re supposed to be talking about open source docs here, so here’s one from a set of developer tools for PHP:

“There are four ways to start a session. Two are wrong”.

Because, just as with the chainsaw example, there’s nothing quite like telling people the wrong way to do things.

It leads me to another one that I come across all the time in open source docs. This one is a little more subtle, but it’s also much, much more prevalent, so I’ve got a few examples here, maybe you can spot the common theme:

“simply open konsole”.

Well, I guess that’s easy enough, if you can find it in the menu. Actually, if we’re talking KDE, if you can find the menu.

“The easiest way to do this is to simply”

Not only is it simple, it’s also easy! Yay us!

“Simply download the patch here:”

You have no idea how many times I’ve clicked a link like that either led to a page with a list of patches longer than a Tom Clancy novel, led to a page with no patches at all, or led to a 404.

“Simply type in the following commands”

Easy to type maybe, provided you know what all the switches do, understand all the parameters you’re setting, think in bash script, and have half a clue what you’re trying to achieve.

“Simply install the latest version”

Yeah, easy, why haven’t you finished that yet? And another one:

“Simply install the package”

Yup. Have you ever tried installing anything on Linux? If it’s not in the package manager, you’re on your own. And another one

“Simply install the package from their website”

As long as no one has moved it or changed it in the meantime. And my own personal favourite:

“<div class=”entry”> disappears entirely and <h3 class=”comments”> simply becomes <h3>”

Wow! Why didn’t I think of that! So simple!

Another quote, this one from Edward Gibbon. He said this many years before the concept of open source existed, but his words pretty much sum up many open source writers:

“Unprovided with original learning, unformed in the habits of thinking, unskilled in the arts of composition, I resolved to write a book”.

In open source, we all jump in and do what needs to be done, regardless and sometimes despite where our skills might lie. We’re all being forced to adapt to our environments in strange ways, stretch our skillsets, and do things we would never in normal circumstances do. So open source development tends to mean we all step in and do what needs to be done, but the main problem with that is the documentation isn’t recognised as “something that needs to be done” until fairly late in the piece. It’s at that point that someone realises that there’s a hole that needs filling up, and so some random person will be asked to step in and fill that gap.

Of course, the other problem that’s present in open source documentation is that of the amateur, and this doesn’t just apply to writing, either. People come to open source for a variety of reasons, but one of the main ones is to gain experience in their field, or to create or contribute to something that they can add to their portfolio. And I’m no stranger to this either, I frequently recommend contributing to an open source project as a good way for potential writers to start out. The problem with this of course is that in some projects, you end with a situation where the seasoned writers are burning out, getting run over by busses, or – heaven forbid – busy with actual real careers where they get paid real money and everything, and the majority of the grunt work is being done by people who – like Mr Gibbon – really didn’t know what they were doing. Not to say it’s a bad thing having new writers on a project, but like all the good things in life, it needs to be in balance. It’s no good having forty-seven amateurs and only one person who actually knows what’s going on, especially if it’s not a full time job for any of them.

In certain professions, it is natural to assume that the people practising them are skilled professionals. Doctor springs to mind, as does actor, and anything that involves sharp or particularly heavy machinery. Or pipe wrenches. Most people could at least have a good guess at what qualifications you would need to become a lawyer, a teacher, a plumber, a solar panel installation specialist, or a computer engineer.
But writing is still very much a dark art. And while technical writing certainly doesn’t have the mystique of, say, literary fiction or even a good horror writer, it is definitely considered a black box in many ways. And that, right there, is the problem. People don’t understand the skill required, the techniques employed, the training we have, even though we see product of writing work all the time. This, unfortunately, tends to mean that people figure it’s easy, and anyone could do it.

So you end up with a situation where the documentation becomes something of a hot potato. Everyone knows it needs to be done, nobody wants to do it, eventually it lands on the one person who was stupid enough to admit to either knowing a typesetting language, having some felicity with a word processor, or once having had a job where they sat next to someone who had to do some writing.

Basically, we’re surrounded every day – not just in open source – by stuff written by people who barely know how to string a sentence together. And it’s not just about choosing the right ‘your’ either. It’s also about organising the information in a way that makes it … well, informational.

The next quote is from one of my favourite authors. His name was Eric Blair, but he was better known as George Orwell. He’s most famous for giving us the notion of Big Brother, but he also left us with some fabulous writing advice. His most famous writing advice was given in 1946 in the form of an essay called “Politics and the English Language”, which is where this quote also comes from:

“In certain kinds of writing … it is normal to come across long passages which are almost completely lacking in meaning.”

And while this may well have been true in 1946, unfortunately no one must have been listening, because it’s only gotten worse.

This is from a ZDNet article that was written about a product I’m currently writing for, it says:

“CloudForms, which is based upon the company-sponsored DeltaCloud project that is now part of Apache– offer sophisticated resource management, application deployment services and Infrastructure-as a Service offerings that help IT adminstrators implement private and hybrid clouds”.

It doesn’t end there, they go on to say:

“The platform consists of a cloud engine for high level automation and abstraction services across multiple virtualization hypervisors and virtualized clusters, an application engine and system engine for comprehensive application lifecycle management across multiple cloud providers and various Infrastucture -as-a-Service offerings including storage, messaging and high availability services”.

Basically, that is 88 words that are completely devoid of meaning.

I’ve left the typos in for your own amusement.

Which brings me neatly to my next piece of wisdom, this one from the web comic author Randy Milholland (Something Positive), who said that

“Typos are very important to all written form. It gives the reader something to look for so they aren’t distracted by the total lack of content in your writing.”

Which could easily explain most of the Register’s articles these days.

So let’s explore this problem a little more. In order to solve a problem, though, we need to define exactly what the problem is, and that’s where open source makes it difficult, because open source encompasses much more than just Linux, and one solution is never going to apply in all situations. So, let’s take a look at the issues. There are of course two broad types of open source project:

There’s the cathedral type, where you have some piece of software that’s been developed internally by some company and then released as open source, or the flip side of that is the RHEL model, where they branch an existing project, which is then worked on internally and released to the public again.

Then you have the bazaar type, which is what many of us tend to think of automatically when we say “open source project”. This is where some teenaged genius has a brilliant idea and then somehow convinces everyone else it’s brilliant and they should contribute to it as well.

So of course, I can go on at length about how documentation is handled in the cathedral version. In Red Hat’s case, of course, we hire people, train them, and then get them to pump out documentation. For the most part, what they pump out is pretty good, but that’s to be expected when you’re putting effort in to finding and hiring the people best suited for the job.

Another interesting one that’s more or less in the cathedral category is Libre Office. They’re created by a seemingly endless stream of volunteers, but are extremely susceptible to the newbie problem. There are one or two community elders who know where everything is and what needs to be done next, and there’s a steady flow of people who drift in, do a few things, and then drift out again. It works, oddly enough, and if you’ve ever used Libre Office documentation then you would know that what they pump out is pretty high quality.

So let’s move into the bazaar-style projects. Of course one of the best ones for documentation is Gimp. Their user manual is a thing of wonder, and they also have an amazing array of tutorials. I haven’t had much to do with the gimp docs community, but as far as I know they have a relatively tight knit group of core documenters, which says a lot about how having a core group of experienced writers can really help your overall documentation.

And it’s also interesting to contrast Gimp to Inkscape. Inkscape has a really robust community of contributors, but they haven’t had the documentation focus that Gimp has.  For some time they’ve had a fairly robust users manual over at the Floss Manuals site, though, so perhaps they just haven’t seen the need to expend energy on doing it within the project.

Of course, it’s important to remember when we’re talking about Gimp and Inkscape though that in terms of bazaar-style open source projects, they really are the cream of the crop. To get a more realistic view, let’s look at a little tool I was trying to get working not so long ago called ‘recordmydesktop’. This is their documentation page, so the fact that they have one is a good start. You might notice the last time it was updated though. 2008 in the case of the FAQ, and 2007 in the case of the manual. I won’t get started on the manual itself, because we only have forty minutes.

So we’ve more or less ascertained that most documentation sucks, and open source documentation tends to suck slightly harder than the rest. The next question then is, what are we going to do about it. If you have lots of money, the answer is easy … pay a professional writer to do it. Depending on who you get, and how much money you give them, you should end up with something pretty reasonable. Hopefully.

If you’re in this happy situation, then you need to go looking for someone who is a writer first and a technology nut second. There’s a fairly common thought, especially amongst the IT crowd, that you can’t document a product unless you have a full understanding of the technology behind it, and possibly several decades of experience in using it. Well, I’d like to stand up here today as living proof that that statement is a lie. Complete and utter fiction. The skills of a professional technical writer include being able to wade into a product they’ve never seen or used before, and be able to document it fully. That’s because professional writers are trained in the art of audience analysis.  They approach the product in the same way as a user, which means they are much closer to the learning curve that your users will be going through, which ultimately helps them document it.

Let’s have a car analogy! Imagine you’re a mechanic, and someone has asked you to describe a car to them. There’s a reasonable chance that you’re going to start off describing how the car converts fuel to energy, which drives the engine. But if that person has never seen a car before, what they really need to know is that it is a box with wheels that can move people from place to place, before they understand catalytic conversion.

Of course, money ain’t always easy to come by, especially if you’re in the open source space. But that’s not to say that you can’t get writers to write for free. The good thing about writers is that they tend to have this undeniable drive to … well … write. It’s that drive that creates such wonderful things as NaNoWriMo. National Novel Writing Month – or NaNoWriMo – is where people sign up to write 50,000 words in 30 days. For free! I’m sure many of you think this is completely nuts, and I’m sure you’re probably right. But there’s lessons to be learned here, too.

The biggest lesson we can take away from things like NaNoWriMo is that if you give writers an attractive writing environment, they will come to write for you simply because it seems like it might be fun to do. And so this means you might need to put a little bit of thought into how you project is going to be documented, in order to be able to make that authoring environment as attractive as possible.

Briefly, I’d like to hark back to what I said earlier about Red Hat. Red Hat have about 90 people in the documentation group now, with more than half of them being writers, and the rest translators. And we haven’t slowed down hiring (Incidentally, if you want a job …). Why is it we can find so many writers? Well, a lot of it has to do with the environment we offer potential new writers. Can you see a pattern emerging here?

So here’s my list of great writing environment factors, whether you’re paying your writers or not:

Give writers freedom in the tools they use. This allows experienced writers to use tools they’re familiar with, and to adjust and improve the way they work with your documentation. If you have always produced documentation in a word processor, and you have a great writer come in and want to start working in Docbook XML or LaTeX, then let them. If they’re experienced enough to know what that is and how to make the change, they’re worth being flexible for.

On the other hand, provide a simple structure and process for producing documentation. Don’t make people jump through hoops to contribute to the docs. This helps new writers on the project get up and running quickly, and it helps people who are not proven writers get started. We all know how important it is for our contributors to be able to submit their first patch quickly and fairly easily, so that they get that hit of satisfaction and stick around. It’s exactly the same for writers. Make it easy for them to do quick tasks like fixing spelling and grammar mistakes, and maybe have an up to date list of smaller projects that need doing, ready for when new people sign up to the mailing list.

 A robust documentation team will pick up many, many bugs for you. Within Red Hat, a large proportion of the bugs found in our software before it’s released, is found by the documentation group. And that’s aside from the other positive benefits that good documentation can bring to a project, including the single biggest factor, which is decreasing support calls. Make sure you acknowledge the work the documentation team does. Make sure that whenever you mention contributors or volunteers, that those on the docs team are mentioned as well. Don’t include them as an afterthought, or as a generic group called “the documentation team”. Name them! Make sure they know you understand and appreciate that the work they have contributed is just as important as the work contributed by developers. And this works to attract more writers too: if people see that writers are acknowledged and appreciated in a project, they’re more likely to feel as though they too will be rewarded by joining.

Recognise writers as experts in their field. If they tell you that something doesn’t read well, or they recommend that you choose a different way of expressing something, listen to them as you would another developer. You don’t have to agree with them every time, because that’s not the way the world works, but recognise that where you know how to sling code, they know how to sling words. And if they’re coming to you and saying that your documentation sucks, perhaps you should give them an opportunity to step up and make it better.

And finally, ensure you have a positive and welcoming community. I know this isn’t easy, but it’s probably the single biggest recommendation I can make. As a job classification, writing – even highly technical writing – does not suffer from the same gender imbalance as software development. Roughly half of your potential writers will be women, and roughly half will be from a background other than white and north American. And it won’t necessarily be the same half. If you don’t have a code of conduct, and if you don’t have a community that actively welcomes and supports women and minorities, then you are cutting down your pool of potential writers by well over half. And I don’t know about you, but that just seems dumb to me.

So I’m going to leave you with some final words of wisdom from the Polish writer Stanis?aw Jerzy Lec: “Advice to writers: sometimes you just have to stop writing. Even before you begin”.


This blog post was originally a talk given at the 2011 Open Source Developers’ Conference in Canberra on 16 November, 2011. Video of this talk is now up on my videos page.


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.