On Writing, Tech and Other Loquacities

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

I've been wondering what to do about the kitchen in the new place in the short term, but the answer has hunted me down, it seems. I was thinking that if I can just change the colour of the benchtops somehow, it would make me a lot happier. My first idea was to buy new laminate, and somehow glue it on top of the orange stuff, but after some investigation, it seems a lot more difficult, expensive, and time consuming than I was willing to deal with. Especially considering the kitchen will be entirely replaced within a matter of months (funds permitting!). Anyway, the renovation forums - combined with a touch of Google-fu - have come to my aid again, and the answer lies in this: paint!



White Knight Paints do a beasty called a "laminate paint", which is designed especially for - you guessed it - painting laminate! The beauty of it all is that you don't need to pull the sink and the stove and everything out to do it, you can just mask them off. And the really cool bit about this whole adventure? My brother is a spray painter ... wheeee!

From the comments section on the skepchick article regarding the "Ban the Burka" furor:

ekimbrough // Jul 3, 2009 at 5:14 pm

The argument for banning burqas is an argument that shoots itself in the foot. We don’t like burqas because they’re a symbol of a ruling authority forcing a restriction onto women because the women aren’t respected enough to be allowed to decide for themselves. So, what would ban on burqas be? Uh…That would be a ruling authority forcing a restriction onto women because the women aren’t respected enough to be allowed to decide for themselves.

….oops…..

Never was a truer word said.

I'm not going to go into detail on this, it really does stand on its own. I will however, say this:

If Terrie-Anne Verney is sacked, so should Virginia Haussegger.

Let them say it in their own personal ways, but don't give them the national broadcaster as a platform.

What's so wonderful about being a little boy anyway? Why is that necessarily any better than being a mouse? I know that mice get hunted and they sometimes get poisoned or caught in traps. But little boys sometimes get killed, too. Little boys can be run over by motor-cars or they can die of some awful illness. Little boys have to go to school. Mice don't. Mice don't have to pass exams. Mice don't have to worry about money. Mice, as far as I can see, have only two enemies, humans and cats. My grandmother is a human, but I know for certain that she will always love me whoever I am. And she never, thank goodness, keeps a cat. When mice grow up, they don't ever have to go to war and fight against other mice. Mice, I felt pretty certain, all like each other. People don't.

Yes, I told myself, I don't think it is at all a bad thing to be a mouse.

Roald Dahl "The Witches"

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

I've been lucky enough to be present at a few conferences now where there has been what has been termed the 'Twitter backchannel'. One formal, and a few informal. I gave a short talk at one of the informal ones, as well.

The term 'backchannel' refers to a conversation being held by the audience, in addition to and alongside the formal channel of the speaker talking to the audience. Increasingly, Twitter is being used to enable this conversation, as it is fast, easy, and very accessible using mobile devices. With Twitter readily available on iPhones, netbooks, and all manner of mobile devices, it's easy to make a quick comment about the subject of the talk, especially if you feel strongly one way or the other about the subject matter. But what happens as this trend grows? As a greater proportion of audiences take advantage of this easy method of commenting, what happens to the value of the medium?



It is becoming more and more common to enable a commentary about a topic. Through 'comments' sections on news stories, blogs such as this one, and other social media. Even traditional mass-communication devices like television, newspaper, and radio are increasingly using social networking to create a backchannel to their stories. It is now perfectly ordinary for radio presenters to discuss the text messages and 'tweets' they have received on their programs. While the model is not perfect, it does create a dialogue between traditional one-to-many media outlets and their audiences that has never existed before. And so it is in this environment, and with this public expectation of dialogue, that the backchannel has been created.

In general, a speech at a conference offers only a single communication channel. The interesting part is that the backchannel doesn't offer reciprocity. In fact, the speaker is (in most cases) completely ignorant of what is going on in the backchannel until they've finished speaking. The first conference went to with a formal backchannel actually prompted one speaker to comment that the only thing that wasn't great about it was the fact that he couldn't see it happening. He jokingly asked for a screen at the front so that he could see what people were saying. But how much of a joke is that? The backchannel can often provide critical information to a speaker - information that could be responded to, acted on, or qualified by the speaker while on the podium. It could also give them valuable feedback that they would otherwise have received face to face, but because of the existence and nature of the backchannel, they may never receive. It makes the backchannel an ineffective medium for dialogue between the speaker and the audience.

With that in mind, can a whole audience full of people tapping on their mobile devices really be paying attention to the speaker anyway? There's an argument that says at least the audience is commenting on the speech itself, so it can't be all bad. It really does feed into our newfound short attention spans though. It has been documented many times over that society's increasing focus on instant gratification and constant entertainment is ruining our ability (or our will?) to be able to focus on one thing at a time - and one thing only. Perhaps by offering two attention-getters - the speaker, and the backchannel - on the one topic, the speaker is more likely to get the audience to think about the topic, instead of drifting off and thinking about something else? More research needed, perhaps.

So what benefit does it bring? It might not give much apparent benefit to the speaker as an individual, but it does bring benefit to the conversation as a whole. If the speaker's purpose is to get everyone paying attention to them, and to increase their own visibility and importance, then the backchannel will probably only serve to detract from the purpose. If, however, the idea is to create a conversation around a topic; to raise awareness; to get people thinking; to encourage action; then the backchannel might just be the way to do it. Not only does it get the people in the room excited about the topic, but it also creates a way to reach outside the room, to the followers and the followers of followers of the members of the audience. If the idea is good, and the support strong, it could potentially cause a waterfall of cascading information, the beginnings of a grass roots movement.

The Twitter backchannel is a new concept, and at least in some ways, entirely inappropriate for many traditional conference talks. But it's also new, relatively untested, and contains enormous potential, if it can be tapped in to effectively. Until it's been fully developed, and put through its paces in all manner of situations, I can't hold judgement, and I don't believe anyone else can either. Hate it or love it, it's the way of the future. Let's see how it gets used before we make a call.

I like the word zealot. Much more than I like the trait, I must admit. What's interesting is how much the term gets used to describe people who use Linux. And as much as I wish it weren't so, I can see why it happens too. All too often, Linux users are seen to be ranting on about why the whole world ought to be using it. Yes, I like Linux too, but what kind of dream world do some of these people inhabit? It really comes down to what you do with your computer, and what tools are best for the job. If you need to whack a nail into the wall, you're going to need a hammer to do the job properly - half a housebrick might work, but it's going to be time consuming, you might waste a few nails doing it, and you're probably going to have added a few new and interesting words to your vocabulary by the time it's done.

To get away from the metaphor, and into reality, I was lucky enough to give a talk at a computing group recently. The audience was primarily Windows users, with a scattered few hobbyist Linux users, and the talk was all about debunking Linux myths, and trying to give a realistic impression of what Linux could offer. At the end of the talk, I took questions, and there were a lot of them (as an aside, there's nothing better than an interested audience, let me tell you!). The one that really stood out for me, though, was an older gentleman who said "I have a Windows machine running at home, and it does everything I need it to. Why should I switch to Linux?". My answer might have shocked some of my audience, because after banging on for the better part of an hour about how great Linux was, I told him, "you shouldn't." Why did I tell him that? Because Windows, in his words, did everything he needed it to do. Why should he be subjected to a learning curve that he didn't need? Why should he be forced to learn new ways of doing the same old things, when he knows how to do them now? Why should he be pushed into the proverbial deep end, and told to swim, when all he wants to do is splash in the shallows? More to the point, who am I to tell him he ought to?

I know a lot of people have an answer to that, and it generally goes along the line of "but Linux is free software - it's better for the community, it strengthens the greater good, and anyway, Linux just runs better." I can agree with that too, for what it's worth. But why does Linux need to worry about rate of adoption, the number of global users, and whether or not it's a 'true competitor' for Microsoft or Apple? And the answer to that lies in the answer given before - it doesn't, because it's free software, it's better for the community, and strengthens the greater good. It's a very circular argument, really. Free and open source is a very worthy cause. But because it's free and open source, it doesn't matter how many people adopt it.

By running around like idiots, claiming that everyone should be using Linux and contemplating a Windows-free world, the Linux community (and I count myself among them) are shooting themselves in the foot. Why not step quietly through the world, present your option, and then let people decide for themselves. They'll either come to Linux, or they won't. Either way, it doesn't hurt the cause. The cause, after all, is software freedom, not Linux on every desktop. Quite frankly, software freedom is something I'm more than willing to fight for, but a monopoly? Isn't that what we're fighting against?

An error does not become truth by reason of multiplied propagation, nor does truth become error because nobody sees it.