We are here! We are here! We are here!

Pixar has a new movie out (warning: horrible flash site with sound) in a couple of weeks. Naturally, T is itching to see it. It even sounds like a decent story. The main character ties a whole heap of helium balloons to his house, to embark on a long-wished-for holiday. The climax is seemingly built around a somewhat irritating small child. The main thing I noticed, though, like a scratch that you can't quite itch, is the lack of female characters. Again.

Why, Pixar? At least a few of the others have had female sidekicks. Up lacks even that, from what I can see. Of course, I'll take T along to see it, as I have done with the others. She'll love it, of course, and want a copy on DVD. But what message will she bring home? How much debriefing will I need to offer this time?

Of course, Pixar isn't alone. The last one to really get my goat was Horton Hears a Who. I loved the basic premise of this book, but the Mayor's 96 daughters (all caught up, appropriately for their gender, in issues such as homework and hairbrushes) and the one son, who - quite naturally - saves the day. I'm sure at least one of those 96 daughters could have been a strong character, but we never got to hear about them.

And yes, I know Coraline's out. I'm personally quite excited about it. But I'm afraid it's too scary for my daughter's often quite fragile constitution. I might have to go see it myself, and pass judgement then.

When are going to see a genuine kid's movie, with all of Pixar's charm and humour, but with a female in the driver's seat? It's not that much to ask, is it? After all, over half of our children are girls. Give them something to watch, and love, but also give them something to aspire to.

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