On Writing, Tech, and Other Loquacities

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

Leave a comment

Sssh! Sneak Preview!

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

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

See you soon, America!


Leave a comment

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!


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