On Writing, Tech, and Other Loquacities

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


The Grass is Greener on The Open Side

The Grass is Greener on the Open Side

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

Freedom, and how it relates to beer

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

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

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

Have you got a licence for that thing?

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

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

Decision time!

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

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

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

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

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

Arguments, naturally

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

I’m still not sold

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

It’s not just about the freedom

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


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


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



Leave a comment

Society of Editors Playing in the Grass

Some time ago, I gave a web seminar for the Society of Technical Communicators (STC) in the US, which was an interesting experience. Considering it occurred at 4am local time, I’m not entirely certain I was at my best, but luckily I’ve been given the opportunity to repeat the talk at a more reasonable time. The Canberra Society of Editors also welcomes the ACT branch of the Australian Society of Technical Communicators (ASTC) to their meetings every month, and through this happy alliance, I will be presenting The Grass is Greener on the Open Side on 27 April at 6:30pm, at the Australian National University.

I’m constantly surprised with how closed the technical communicator’s world can be. In an industry where Adobe and Madcap rule the roost, if you mention that you work in open source, or use open source tools, people tend to nod mutely. Either they have no idea what ‘open source’ actually is, or they have no idea what working with open source tools might actually entail. And so this talk was born. It is intended to be treated as Open Source 101 for technical communicators, essentially.

And of course, if you can make it along, I’d love to see you!



There’s nothing wrong with Ohio

(Except the snow and the rain)

It looks as though I’ll be winging my way back to the United States again shortly. I’ve been asked to speak at the Open Help Conference in Cincinnati (and one day soon I’ll learn how to spell it!), Ohio on 3-5 June.

If you’re half as dedicated as I am to American candy, get your orders in now. There will only be so much room in the suitcase …


Leave a comment

The Language of Marketing

I was absently staring at a new tube of toothpaste this morning as I washed my hair. You have to look at something, right? This one declared “healthy, whiter teeth for longer”. An image of extremely long (but healthy and white) teeth filled my mind, and was immediately pushed out by the technical writer in me asking “whiter and longer than what, exactly?”

Most marketing slogans give technical writers the screaming heebie-jeebies. Not only do they make spurious and vague claims like ‘more fibre’, ‘less fat’, and ‘20% bigger’ with alarming regularity, but the adjectives! I have no doubt that it is actually possible to sell things with sentences that contain only one adjective. And if they do need more than one, I’m sure a comma wouldn’t kill them. I could rant on the folly of adverbs, too, but that is a whole different article.

Why are marketers such terrible writers?

Because customers expect spin, and spin is easy to write. All you need is a handful of adjectives and a call to action: “The new fruity refreshing Globswoddle Fizz is now available. Experience the heady taste of summer today!”

While yelling at the toothpaste tube in the morning might make us all feel better, it is not likely to turn us into marketers just to help an obviously flailing industry. I finished my marketing degree about three weeks before I decided that the marketing industry was the last place in the world I wanted to work. Eventually, I became a technical writer instead, and discovered that I had inadvertently ended up working in marketing after all. Every word we set to paper is marketing in one way or another. If it is going to be read by a customer, then it needs to sell the product. But the last thing we want to write is spin.

Why are writers such terrible marketers?

Because customers want anything but spin, and while spin is easy to write, spinless marketing is not so easy.

Spin is wanted and welcomed in places where it is expected, like product packaging and on the airwaves. When our customers read technical manuals or help text, they are looking for a solution to a problem. If they were suddenly faced with the empty promises of spin, they would lose faith in the documentation, and possibly the product.

However brutal honesty is not required, either. Product documentation should not tell customers that the product cannot fulfill their expectations. Every question needs to be anticipated and answered. The documentation must give the customer hope that their problem can be resolved, their task completed, and their sanity retained in the process.

Effective documentation never tells the customer that a product is terrible (even if it is), and it never tells a customer that they are stupid (even if they are). It never makes over-inflated claims of software brilliance, and it never assumes greater-than-average user intelligence.

Somewhere nestled in there is product documentation that shows the product in a positive light, without the hard sell. Sound easy? Like most technical writing, it sounds easy until you actually try to do it. Some tips for getting started with spinless writing:

Kick adverbs, take names.
Adverbs are a big red flag for spin. Be ruthless and cut them all out. If your sentence requires a modifier, consider what you are really trying to say. If it forms part of an instruction or description (‘The widget can be fully removed by …’), reword it to remove the adverb (‘Remove the widget by …’).

Never call anything ‘simple’.
If you tell your users that something is ‘simple’, ‘quick’, or ‘easy’, and the customer struggles with it (for whatever reason), you are essentially telling them that they fail at life. Try not to insult your users.

Mind your adjectives.
Adjectives are fine in their place. Use them only where necessary, though, and try not to use more than one at a time. (‘Locate the red button’ is fine, but avoid ‘Locate the large, shiny, red button’ that is next to the ‘tiny, silver, shiny lever’).

Know your stuff.
If you can’t describe your topic in a single short sentence, you don’t understand it well enough, and it becomes too easy to succumb to spin statements. You need to be able to give succinct and accurate descriptions for each and every component part, as well as the product as whole. If you are not able to do this, continue to research your product until you can.

Understand the enemy.
As modern humans, we are largely desensitised to advertising, simply because we are so totally immersed in it. Start noticing it. Analyse what language is used, the sentence structure they’ve employed. Work out how you would re-write it to send the same message, but without the spin.

Edit with a knife.
Never say more than you need to.


This article was originally published in Words: A Quarterly Bulletin for Technical Writers and Communicators. Volume 3, Issue 1: February 2011, with the following bio:

Lana Brindley has been playing with technology since that summer in the 80’s when she spent the whole time trying not to be eaten by a grue. She has been writing since she could hold a pencil, and is currently writing technical documentation for Red Hat. Lana holds business degrees in marketing and information systems, and with any luck will have a technical communicators degree by the end of the year. She works from her home in Canberra, Australia, and occasionally leaves the house in order to berate university students and conference goers about passive sentence construction.

This post has been cross-posted to fossdocs.


Leave a comment

MODY3 for the newly diagnosed

Receiving a MODY3 diagnosis can be a threatening, frightening time. However, by understanding the disease, and knowing what to do about it, you can live a long and healthy life. This booklet will explain what MODY3 is, and will outline some of the changes you will need to make.

Diabetes mellitus refers to a group of diseases that impact the pancreas and how the body stores and uses both glucose and insulin. Maturity onset diabetes of youth (or MODY) is a rare genetic form of diabetes.

There are three main groups of diseases that fall under the diabetes heading:

  • Type 1 is an immunodeficiency disorder, where the pancreas no longer produces any insulin. People with type 1 diabetes require injections of insulin to stay healthy.
  • Type 2 is a progressive disease, where the pancreas will gradually stop producing insulin in the quantities required. Additionally, people with type 2 diabetes will exhibit insulin resistance, where they  can no longer effectively use the insulin their pancreas produces.
  • All other types. This includes latent autoimmune diabetes of adults (LADA), which is a form of late-onset type 1 diabetes; and maturity onset diabetes of youth (MODY), which is a genetic form of diabetes. These types are sometimes referred to as ‘type 1.5’.

Many people with MODY are never officially diagnosed, as it requires lengthy and expensive genetic testing, and even those results can be inconclusive. You might have been diagnosed as one of the other types of diabetes, and your progression has caused your doctor to suspect you have MODY, or you might have been diagnosed as MODY simply because you show none of the usual signs of type 1 or 2 diabetes. Do not worry too much about having an official diagnosis, though. Enough is known and understood about the management of diabetes—and MODY—to be able to manage your condition very well. Over time, you and your medical team will be able to determine with greater certainty what type of diabetes you have, and how best to treat it.

Despite the name, maturity onset diabetes of youth is not late-onset type 1 diabetes. MODY comes in six known forms, although this number could climb as research continues into the area. MODY is referred to as ‘monogenic’ meaning that it involves only one gene, unlike the more common forms of diabetes that have more complex causes, and involve two or more genes. The types of MODY are differentiated by the gene that is involved. About 2% of all diabetes diagnoses are MODY, and about 70% of all MODY diagnoses are of the type MODY3. MODY3 is caused by mutations of a gene on chromosome 12 called the HNF1? gene.

Generally, people with MODY3 produce a very small amount of insulin or none at all. However, if you have MODY3, you probably do not have very high insulin resistance. This means that that you can use any insulin your body produces or that you inject effectively.

To keep reading, download MODY3 for the newly diagnosed

I wrote this manual as a final assessment item for uni. I have no intention of updating or maintaining the document at this stage, however if there is sufficient interest in it as an information resource, I could possibly be convinced 😉


Leave a comment

Keeping It Stupidly Simple

Everyone has heard the old adage about the “KISS Principle: Keep It Simple, Stupid”. Easy to say, easy to remember, but often hard to do. At least, hard to do well. When we simplify our language, it often comes across as patronising, dumbed-down, or just plain rude. So how should Stupid keep it simple, without making it stupidly simple?

Consider the sentence:

“Insert the writable media into the optical disk drive.”

It’s not horribly bad as it stands, but it could be made simpler. Here’s one version:

Open the disk drawer by pressing the button on the front of the drawer. Place the CD into the tray with the label facing upwards. Close the drawer by pressing the button again. Do not force the drawer closed.”

Well, it’s simpler. We’ve lost some of the more easily-confused terms such as “writable media” and”optical disk drive”, replacing them with more common and regular words. We’ve given more specific instructions about the actual process of performing the task, which can help with understanding, and also give users more information about troubleshooting. This would be great for a manual that is introducing people to computers for the first time.

But what if I were to tell you that this instruction is to go into a Developer’s Guide, that is, a book read and used by software developers? All of a sudden, the new version of this sentence has become horribly patronising. It is safe to assume that a software developer has opened a disk drawer once or twice before, and probably doesn’t need to be given explicit instructions about where to find the button. They probably also understand the terms “writable media” and “optical disk drive”. So we’re back to where we started from. How do we simplify the sentence for this audience without speaking down to the audience?

Think about what the sentence is trying to convey. How would you explain this to someone who is sitting across the table from you? Imagine you have a friend who is a software developer. You go around to their house, and they ask you a question about this product you’re working on the manual for. How would you explain it to them? If they said “what do I do now?” would you respond by handing them a CD and saying “Insert the writable media into the optical disk drive”? Probably not. I can just about guarantee that you would say something more like this:

Put the CD into the disk drive

So there’s your answer. It’s not patronising, it’s not too complicated. It uses terms that everyone is familiar with, and isn’t couched in lengthy words and stuffy language. It gives all the information the user needs, and isn’t drowning in information we can safely assume they already know.

The problem, of course, is that keeping it simple is not always simple. Corporate language is increasingly creeping into the everyday. Keeping it out of technical documentation is becoming increasingly difficult. Of course, if the product you are documenting is called a “Synergy Manipulation Process Leveraging Suite” there’s not much you can do about that. You can, however, ensure that you give information about the product in plain language. Explain what it does (other than leverage synergies!), explain how to use it. Try standing up and reading your text out loud. Try explaining the processes and concepts to a friend and take note of the language you use. Look at each individual word and think “is there a simpler word that I can use here?”. Keep your sentences short and to the point. Avoid repetition unless it is absolutely necessary.

Just yesterday, to give a real-world example, I saw a blog-post titled “Marketing Leaders Should Help Create the Next Generation of Australian Multi-Channel Retail”. Now, I don’t even know what that means (and surely it needs another noun on the end … “retail what“?). I clicked on the link, and read the first sentence, trying to work out if it was something I might be interested in, and saw whole sentences full of nothing but corporate-speak. Needless to say, I didn’t read any more. And therein lies a valuable lesson – write for your audience, but never write for the sake of putting words on paper. Even if your audience is a group of corporate-types in suits, who live and breathe corporate-speak, don’t write an empty document, filled with empty words. Make sure you have something to say, and then say it as simply and as accurately as possible.

The pictured quotes on this page have come courtesy of Andrew Davidson’s wonderful Corporate Gibberish Generator

This blog post has been cross-posted to Professional Open Source Documentation


Leave a comment

FOSS Training

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

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

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

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

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

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

Cross-posted to FOSS Docs

Leave a comment

The beast within

Writing is the only thing that, when I do it, I don’t feel I should be doing something else.

Gloria Steinem

National Novel Writing Month (NaNoWriMo) is coming up again. And so, like many other writers (both professional and aspiring), I’ll be setting aside the thirty days of November to pump out 50,000 words of a novel, or about 1,600 words a day. This is in addition to the thousands of words I pump out every month as part of my role as a technical writer, of course. The question here is, what on earth makes someone who writes all day for a living, want to go home and write all night as well? It sounds like a Dr Suess story: “Oh I say, we write all day. Write, write, we write all night”. The really peculiar thing is that I’m not alone in this endeavour. There are many tech writers out there moonlighting as novelists every November. Don’t try to take a tech writer out to dinner in November, unless you’re willing to have them with their laptop out at the table … taptaptaptappitytap


I suspect writers are born, not made. That’s not to say that good writers are rare, I actually suspect that they’re quite ubiquitous. Many of them never actually become writers. They become all manner of other things – butchers, bakers, and candlestick makers – but that drive to write exists within them still. They might write a private journal, be secretly working on a novel, submit letters to the editor, write lengthy letters to their friends, submit stories to a website, or keep a blog.  Or just wish they had the time.

All of this means that, as a writer, when you meet another in the street, you see that gleam in their eyes. There’s a passion, an excitement, a certain joie de vivre that they only truly experience when they are head down and writing. Have you ever wandered down the street, completely lost in thought trying to work out a plot twist, a character development, a particularly witty piece of dialogue, only to realise that you’re grinning your head off, looking like a loon? Then you’re a writer. And here’s my advice to you: don’t fight it.

I have a stack of manuscripts in my desk drawer. Will I ever submit them to a publisher? No. Will I ever give them the edits and re-writes they really need? No. Will I ever look at them again? Probably not. So why bother creating them in the first place? Because I need to write. There is a living thing inside me that is only satiated when there are words flowing through me. What happens to those words afterwards is entirely irrelevant. I think them up, I write them down, I make sure I like the way they sound, and then I let them live on without me.

So if you share my passion, why not join me in November? And if just one month a year of crazy writing isn’t nearly enough, why not apply for a job?

Cross-posted to http://fossdocs.wordpress.com/2009/09/16/the-beast-within“>Foss Docs


Leave a comment

Creating technical documentation in five easy steps

Writing a book is an adventure. To begin with it is a toy and amusement. Then it becomes a mistress, then it becomes a master, then it becomes a tyrant. The last phase is that just as you are about to be reconciled to your servitude, you kill the monster and fling him out to the public.

–Winston Churchill


Step 1: Planning – who is the audience? What are the book’s goals?

Step 2: Content – what are the chapters about? Where will you get the information?

Step 3: Writing – first draft, review, second draft …

Step 4: Internationalisation/Localisation – will the book be translated? Into what languages?

Step 5: Review – what worked? What didn’t? How will the book be maintained?

This is a very distilled version of JoAnn Hackos’ method. It all seems very easy doesn’t it? It’s a fairly logical progression through the steps. Writing in general is often considered an art, a talent (you either have it or you don’t), a skill, and somewhat mysterious and unique to a small portion of the population. In fact, writing is something that many people can do, and a lot of people can do well. Where it gets difficult is the same place as where any task worth doing gets difficult – sticking with it. Writing is not something you can start on Monday, and have a completed book by lunchtime on Thursday. This goes for technical writing as much as any other style, and it’s where the apparent ‘magic’ comes in. Some people have the ability to sit in a small room on their own for weeks at a time, taking and distilling technical minutae by day, and sipping absinthe by night until – like a miracle – they give birth to a brand new shiny technical manual. And some people … well, some people just don’t. Which is not terrifically surprising, on the face of it.

The idea of writing a book is romanticised in our culture. Everyone ‘has a book in them’; we’re all trying to write the ‘great American/Australian/British/$NATIONALITY novel’; one day, I’ll ‘be the next Hemingway/Dickens/Crichton/$AUTHOR’. How many people have started on the path, only to find – days, weeks, months, or years later – that it has been consigned to the desk drawer, and forgotten? This all leads us to believe, however subliminally, that writing a book is hard. It takes a long time, it is terrifically difficult, and only a bare few make it out the other side. It makes us feel better about the unfinished manuscript in the bottom drawer.

Which leads us to realise why so many versions of the writing ‘process’ exists. If you google for it, you will be spoiled for choice in the methods available. It’s a way of breaking down the mammoth task of creating a book into small, manageable, easy-to-chew lumps. Somehow, five (or six, or seven, depending on the method you choose) small steps aren’t half as scary to tackle as one big one: “Write a book”.

When it comes to technical writing, though, the process has more purpose. Technical documents are very rarely produced in isolation. The book could be part of a suite of documents for one product – the Installation Guide, the User Guide, the Reference Guide; it could be a guide for a product that forms part of a complete solution – the front-end tool, the back-end database, and the libraries; it could simply be a book produced by a large technical company that produces a large range of products. Whatever other books or products compliment the work in progress, there needs to be a consistent approach, a ‘look and feel’ that creates a brand around the product. By following a standard process for each and every book written, that brand is more easily created and maintained, even by many authors, all working on individual projects, and in their own unique ways – absinthe or no absinthe.

Cross-posted at Foss Docs


Leave a comment

Crafting beautiful technical documentation

Writing gives you the illusion of control, and then you realize it’s just an illusion, that people are going to bring their own stuff into it.

– David Sedaris

Technical writing is a strange breed. When you write fiction or poetry or a screenplay, it’s a release, it’s a way of expressing what is inside yourself, and allowing your imagination to creep into the those little crevices in your brain, and poke about to see what squirms. Writing technical documentation is almost entirely the opposite. It’s about getting into the heads of your readers, finding out what makes them tick, how they work, and then presenting them with the information in a way that will make them go “Aha!”. It’s about taking source documentation that would make your eyelashes curl, and crafting it – shaping it, massaging it, chewing it up and spitting it out – into something that not only makes sense, but is useful, intuitive, and – dare I say it – beautiful.

Beautiful technical documentation? Why yes. I think so. Bad technical writing is hard to use, hard to understand, and hard to find what you want. Good technical documentation is intuitive, easy to navigate, and aesthetically pleasing. Good technical documentation is beautiful.

The question, then, is how to create beautiful technical documentation, and how to know when that’s what you’ve got. While it would seem easy to tell when you haven’t got it, it is not always as simple as it might sound. The problem is the same as a lot of artists and craftsmen complain of – getting too close to the subject matter. One of the reasons that engineers can not generally create effective documentation is because they get too close to the nuts and bolts of the thing. They spend too much time looking at the engine of the beast, that they become unable to describe what colour the paintjob is. That is where the documentation team step in – we bring fresh eyes to the project, and are able to look at it from the top down. We can describe what it looks like, what it does, and how to do it, without having to explain how that happens. But once you’ve been working on that single document for months, you’ve been through revisions, and revisions of revisions, you’ve been bombarded with information from the technical team, you’ve had requests for more detail, more depth, and more minutiae … then how do you tell if it is any good? Your advantage – your fresh pair of eyes, your ability to see the big picture, and your talent for information organisation – is no longer whole. Now you are the one who is too close to the project.

A writer of fiction would tell you this: put the book down, step away from the desk. Leave it for a week or two, a month or two. And then tackle it with fresh eyes. A technical writer would scoff – who has time for all that? This book needs to be released next Wednesday!

Often, the solution is to hand it to someone else – a fellow writer – for review and comment. But what about when that option isn’t available either? Every writer has their own method of handling this. What I do is this: I put it down, not for long, but for an afternoon, or overnight. And I write something else. Something completely different. A blog post, for example, or a chapter of a novel, or a short story. Anything that has absolutely nothing in common with the piece you’re working on. Ensure the voice that you are writing in changes, the topic changes, the emotion changes. Then, make yourself a cup of tea, and pick the book back up again. But don’t start at the beginning. Read it backwards. Read each page, on its own, in reverse order. I even read the paragraphs in reverse order. Start at the last one, and work your way back to the beginning of the book. You’re checking for typos, for sentence structure, for punctuation, grammar, and all that good stuff. By reading it out of order, you’re less likely to drift off and start thinking about something else. You’re more likely to read what’s there, rather than what you think is there.

Then find a blank piece of paper. Put yourself in the mind of your customer: What do they need to know? What are they trying to achieve? Why do they have your book? The answers will be myriad – but list the obvious ones out. You need to think about what your customer knows, and what your customer doesn’t know – that gap is where your book fits.

Once you’re thinking like a customer, pin that list up somewhere you can see it, go back again, and read the book in order. If you’re able, read it aloud, it helps to catch odd phrasing. This time, you need to be looking for flow. Make sure each paragraph flows into the next, that each section flows into the next, that each chapter flows into the next. Check that you’re introducing concepts in order from the top down – start with the big things, and then explain the detail as you go on. Cut out anything that doesn’t fit. Don’t be afraid to cut and paste paragraphs, to taste-test them in a new arrangement.

And the whole time – there’s only one thing you should be thinking about – your customer. If the customer perceives value in your documentation, if your book bridges that gap between what the customer knows, and what they need to know – then they will see the beauty in it.

Cross-posted from Foss Docs