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

Category Archives: Writing

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.

The Eiffel Tower was erected for the Paris World’s Fair in 1889. Nobody much liked it though, and the plan was to let it stand for twenty years, and then tear the horrid thing down. But, here we are, over 100 years since its planned demise, and the Eiffel Tower has become a symbol of all things Parisian, the city of love. What saved it, in the end, was the invention of radio, when some smarty took one look at the the massive towering grid of steel, and thought Merde! Une antenne!

Like the Tower, in open source we rarely set out to achieve what we end up with. Sometimes, we set out not really having any idea what we want to achieve at all, and then we just spend the whole time rolling with the punches. Neither is necessarily bad; in open source, those approaches tend to work just as well as any other, most of the time. Where it becomes difficult, though, is when working on upstream becomes part of your job description. All of a sudden, you have to try and fit the square peg of open source into the round hole of your day job. So where you once had a process of “find something interesting, and then work on that”, you now have a process that involves planning, metrics, deliverables, and probably Gantt charts.

I knew about Linux fairly early on. I didn’t use it of course, I was a Business student, not some nerd. All of which meant I knew about Linux, but I didn’t understand it. Understanding came later, when I picked up an Information Systems major (much to the confusion of my non-nerdy friends, and still to the confusion of my parents). This was in the mid-nineties, so it was also around the time I discovered many new and exciting things: like IRC (a text-based chat system), the early years of Google (back when it was just a search engine), and open source. Some might say that my destiny was more or less set right from that point.

Fast forward a decade or so: I’ve gotten married, had a daughter, and somehow landed an office job at a startup that is only barely funding my MBA and my divorce proceedings. The CTO (employee #3) was an open source nutjob, and along with teaching me what a tech writer was (and blowing my mind in the process), he also managed to reignite that fascination with open source that I had first discovered during my undergrad. As far as I could tell, he achieved work by typing binary directly into the Linux kernel. And while I figured I’d never get to that level of wizardry, I was pretty proud of myself for learning LaTeX out of a book, and actually managing to produce useful technical documents for the company.

Sadly, like many startups, the dream didn’t last long, so when they missed my third paycheque in a row, I started looking for new opportunities, this time armed with a working knowledge of open source, and a desire to write documentation. After some tumbling around, I landed in Brisbane, Australia writing tech docs for Red Hat, rose into a management role, and was then offered a similar role at Rackspace about a year ago. So here I am, with nearly a decade of experience in working in enterprise-level open source documentation.

For those of you who haven’t been lurking on the edges of the open source world for the better part of a quarter of a century, open source tends to fall into two main categories: the single person project that starts as a simple solution to one problem and never really grows much past that, and the bigger more organised project that organisations start to notice. Projects like OpenStack, Libre Office, Inkscape, and Linux itself all fit into this category. When a company starts wanting to offer these products to their customers, they usually hire staff to work on an internal version of them that they can tailor to suit their needs. In this situation, the open source project is referred to as the ‘upstream’ or ‘community’ version, and the branded version produced by the company is referred to as the ‘downstream’ or ‘enterprise’ version.

However you fall in to this weird world of enterprise-level open source, it always starts out with that amazing feeling that someone is paying you to work on something you were perfectly willing to do for free. Eventually that wears off, though, and you find yourself in a place of competing deadlines, mismatched workflows, massive differences of scope, and oddball enterprise requirements. The first thing that will probably be apparent to you is that, despite wanting (or needing) to do more or less the same work on both your enterprise and upstream projects, you probably hold different roles in each group. You could be an entry-level programmer at your workplace, with a core role in upstream; or a manager at work, but a plebeian technical contributor in upstream. Even if you have relatively comparable levels of seniority in both, those roles will necessarily mean different things in each group. This is naturally going to lead to your first real issue:

How do I organise my time and achieve any kind of work/life balance?

Like many lists of hints and tips, this one also starts with the obvious: get organised. As soon as you know your enterprise release dates, let your community know that you won’t be around much during that time. Likewise, make sure your company knows when you’re busy with community work, too.

You won’t always have control over release schedules, especially in bigger projects, but if you do, try and stagger them. Having enterprise releases a set period of time (a month or more) after a community release can be a really good way to do this. This gives you time to take the community release and fiddle with any content that you need specifically for your enterprise customers, and also allows the community time to find and fix the bigger, more damaging, bugs.

Always prioritise your time and pick your battles. Don’t spend three days nursing a non-critical patch through the review process, or arguing over a minor technical point on a mailing list if you don’t have to. If you’re lucky enough to be in a management or senior community position, then delegation can also be helpful. Consider assigning a proxy to attend non-essential meetings or monitor mailing lists.

Finally, don’t fall into the trap of doing only enterprise work while you’re in the office and your boss is watching you, then doing all your community work at home after hours. That’s a recipe for burnout, regardless of how much you enjoy doing the community work. You still need to make sure you get time with your friends and family away from the computer, hit the gym occasionally, and get in some all-important couch time.

How can I be a good community member without looking like a company shill, *and* keep my job?

It’s natural to assume that there will sometimes be conflicts between what your company and your community wants. The best way to handle this is to have already created a culture of honesty and respect in both groups, but that is often beyond your control. Whatever the prevailing culture, though, you can always create your own reputation. Doing this right from the beginning will not only help you when trouble arises, but should also help influence the community’s culture too, even if it’s only in a small way. (If you’re interested in hearing more about creating culture in technical writing teams, come along to my presentation “8 writers in under 8 months: from zero to a docs team in no time flat” at linux.conf.au in Auckland, New Zealand 12-16 January, 2015. The talk should also be made available as a recording after the event)

To create your own reputation, start by being honest with both your company and the community. If you’re pushing a feature upstream because your company wants it, say so, and consider it a use case. If your company has customers wanting a feature then that’s a good reason to do it. If there aren’t any customers asking for the feature, though, question the real reason why it’s being requested, and don’t just pull rank and shove it through the upstream process because your boss told you to.

In order to keep your job, and to keep on being able to work on upstream, it’s important to make sure your company understands what you do in the community. It’s a good idea to have your upstream responsibilities enshrined in your job description, and reinforced at performance review time. If you can, make community contributions and achievements (lines of code, number of patches accepted, achieving more senior community roles) a performance goal. The other side of that coin is to make sure you’re actually doing it. Even if you’re super busy with an enterprise release, spend a little time every day on community work. Even if it’s just triaging a few bugs, or completing a code review or two over your morning coffee. It’ll help the community to not forget that you exist, and it’s a constant push of effort you can show your manager when you need to justify your existence.

How do I get the stuff in the enterprise version into upstream, and back again, without losing my mind?

This is obviously going to be different with every project and every company, but the main thing to do is to create a system. It could be tools based, or just a method of organisation. Perhaps keep a log of things that need to go up or down as you come across them, then check things off the list once they’re done. This is easily achievable with a Kanban board (either sticky notes on a wall or one of the many internet-based tools), and they’re especially useful if you’re working with a team.

It’s also important to be realistic. Don’t just take things upstream (or down) because you wrote them and you think they’re pretty neat. Make sure they’re valuable contributions that suit your stated use case. The audiences for enterprise and upstream will often be different, and different content will be required to satisfy each. That said, always be as fair as possible. Don’t be all take and no give, or vice versa. It’ll only erode your goodwill with the community, or make you That Guy at work. No one wants to be That Guy.

How can we make this better, and less painful? Won’t someone think of the yaks?

Until we’re all plugged mentally into the Internet of Things, and all thought becomes networked, this is likely to remain a difficult problem to solve. Every community and every organisation is different, sometimes radically so, which means trying to get two to work together can be like picking two random cogs and hoping they fit. Sometimes, miraculously, they do, and sometimes there’s just a grinding of gears. Often, though, they fit imperfectly, and those are the ones we can work with.

It’s important that enterprise and upstream are as aligned as possible, and that the organisation has an understanding of upstream concerns. This can often depend on whether your organisation was grown with open source as a core consideration from the beginning, or they only decided to go into upstream later on, as it will massively impact the prevailing company culture.

That said, even a company that decided to work with open source last Wednesday can be taught how to be a good corporate open source citizen. Firstly, the more people working on upstream within your organisation, the better the organisation will get at it. You also want to avoid being the single touch point between your company and upstream. If your company is hiring, make sure you spread the word around your community, and if you find someone looking for work in your community that would suit your organisation, make a case to get them hired. You also want to make sure that you talk about open source with your management team as much as possible. The more your manager understands, the better able they will be to talk about open source to their manager, and so on up the chain of command. If, one day, the CEO declares an open source strategy, then you know you’ll have gotten somewhere.

Finally, don’t be disheartened if you sometimes feel like you’re working two full-time jobs, fighting fires in one and saving drowning kittens in the other. Take a holiday, and when you’re refreshed look at your processes again. If you can take a step back from the trees, you’ll see the forest more clearly and work out the little things you can implement or change to make your life just a little bit easier. Don’t give up, the open source world needs all the corporate advocates they can get, and with your help both your company and your community will be better off in the long run.

This article is the text version of a presentation of the same name to be delivered by Lana Brindley and Anne Gentle at the OpenStack Summit in Paris, France on 3 November, 2014. The talk should also be made available as a recording after the event. It first appeared in article form in the Society of Technical Communicator’s publication Southern Communicator.

I came across this article recently, which states “code is the new resume”. It asserts that people seeking coding jobs should be contributing to open source and using those contributions as proof that they have the skills for the job they’re seeking. I wholly agree, but it got me thinking about the equivalent for writers.

When I have had prospective tech writers come to me for advice on where to start, I have always pointed them towards an open source project that I think would meet their skills and interests. I usually have three main reasons for this. I want them to get experience working with processes within a docs team (particularly a mature docs team that functions well, such as Libre Office or OpenStack). I want to give them an opportunity to get familiar with the tools and programs used by highly technical writing projects (things like Docbook XML and Publican, rather than proprietary tools like Madcap or Adobe). And, perhaps most importantly, I want to give them a chance to write things that they can share with prospective employers.

But contributing to open source docs, while beneficial in career terms, rarely ends up being something you can confidently wave in front of an employer. Rarely, if ever, will you get the chance to create a new document from scratch, something you can call truly yours. And even if you get that chance, rarely will it remain the piece of art you crafted for very long. Open source software moves quickly, and by the time you publish your meticulously researched and effectively written document, there will be a team of hungry writers circling, ready to rip into your virgin words and tear them apart. Within months, your perfect book could be an almost unrecognisable crime against information architecture, full of passive voice and typoed commands, with a title that no longer reflects its content. Certainly not something you want your name anywhere near.

Herein lies the tech writer’s dilemma: when asked for writing samples, what do you do? You don’t want to admit to authorship of something that (through no fault of your own) makes you want to quit the industry, but you also don’t want to say that you’ve been contributing to a project for months and have nothing to show for it. My answer: make your resume your writing sample. You won’t always get away with it, because some employers will ask for writing samples as a matter of course (at which point, having kept a tech writing blog for a while can be very handy. Just sayin’), but having plenty of prose in your resume and making sure it shows off your skills will do wonders for proving you can do the job.

There are no rules saying you need to deliver a two page resume, developed using a standard Word template, to apply for a job. Designers have been handing in creative resumes for decades, and we can take a leaf out their book. Offering something different, something that screams “I’m a writer, and I’m damn good at what I do” is going to make any recruiter or hiring manager stop and look. Remember how many resumes these guys see. Offering a bog-standard resume means that yours will get thrown away at the first typo.

First of all, do your research. If you can, find out what writing tools your prospective employer uses, and use it. If you don’t have that in your repertoire, then use the closest thing you can do. When I applied for my first job that used Docbook XML, I delivered my resume in LaTeX (complete with “Typeset in LaTeX and TeX” in a footnote at the bottom of each page. Nothing like rubbing it right in). I later found out that the hiring manager ran around the office showing it off to all his existing writers, pointing excitedly to the footnote. Once I’d learned Docbook XML, following jobs got that instead. If the company you want to work for uses Word, then deliver a beautifully formatted Word resume (and don’t forget to use styles!). By the same token, be aware of internal culture, and the fact that people get very passionate about their tools. Never deliver a resume built in Word with a .docx extension to an open source company if you don’t want to be teased about it forever after (assuming you get the job despite it, of course).

And, perhaps most importantly, don’t just deliver a series of dot points. This is your chance to prove you can write. Include a fairly long prose introduction, but don’t waffle. Be clear about your goals, the job you’re after, and any relevant work you’ve done previously. If you can, do some research into the company you’re looking to join, and tailor this part to the role you want. Mention how your experience meets their demands, not as a canned response to selection criteria, but as someone who has gone looking for core values and culture clues, and is addressing the human beings that work within that group. Write directly, succinctly, but passionately. Don’t use words too big for the subject (with apologies for paraphrasing C.S. Lewis), make your language casual, but not informal. Get your writer friends to proofread it until you are confident it is perfect. Feel free to email me with your text and I’ll also help.

Don’t make recruiters ask for writing samples. Get creative, use your skills to your advantage, and don’t be afraid to have some fun with it. If you have your own stories of resumes (good or bad), or hiring, please share!

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

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?

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.

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!

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!

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.

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:

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?

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”.

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

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

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

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

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

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

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

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

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

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

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

Where the bloody hell are ya?!

Who wrote all this stuff?

All writing on this blog is the work of Lana Brindley and does not necessarily reflect the view of Rackspace, OpenStack, or any other group with which I am affiliated, except where I have used direct quotes (which are attributed to the original authors where possible). All images were either taken by me, shared under their individual licencing requirements, or obtained as stock photography.