Linux.conf.au

| | 0 comments »
I put my proposal in to linux.conf.au last night. The conference will be in Wellington for 2010, in January. My talk is about technical writing for open source projects, and I've called it "Creating beautiful open source technical documentation". That was a little boring, though, so I gave it a subtitle: "Writing FOSS docs that don't suck". Better :)



For posterity, I'm recording the abstract here:


Creating beautiful open source technical documentation (or: writing FOSS docs that don't suck), is a look into why documentation is so important to open source projects. Many open source projects are created by very small teams of dedicated individuals. In this situation, the importance of effective documentation often goes unrecognised and technical writers are viewed as an unnecessary expense.

Documentation, particularly in an open source project, is all too often created by people who are very close to the technical minutiae. The end result is a documentation suite that starts at a point beyond the users' understanding, and rapidly becomes more complicated. The user gets lost at step one, and throws away the documentation - and the software - as a lost cause.

Standard usability guidelines for software development apply equally to creating documentation. When the focus is put on the user, and what the user needs to achieve, then it is possible to create documentation that takes them beyond merely using the software, and on to enjoying it.

This presentation explores the different facets of documentation usability. It explains how to create documentation that will empower your users, guide them through the somewhat daunting learning curve of using new software, and in the process make your project look fantastic. Beautiful technical documentation might sound like a completely unrealistic fairy tale, but it can make the difference between a successful project, and a wildly successful one.

Crafting beautiful technical documentation

| | 0 comments »
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

The answer to the kitchen question

| | 0 comments »
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!

Ban the burka - or the bigoted leaders of this movement?

| | 0 comments »
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.

Of Mice and Men

| | 0 comments »
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"