Writing style

Writing style

To achieve at least some level of cohesiveness in this collaborative edition, let me lay down some of the ideas I have about writing style. If we all try to stick to these together, the end result - Open Life 2.0 - will be a more pleasant read.

Some short rules

  1. Write in first tense: "I" and "me".
  2. (Especially note: this is not and academic thesis! None of that "this author" passive crap and just in general we are not aiming at being boring here.)
  3. ...on the contrary, I hope you are familiar with the dry and witty humor common among hackers. That is what we want. See Linus's epilogue (Linux Kernel Management Style) for a great example.
  4. Be enthusiastic: Hey, you are writing about Open Source! (At the same time, don't be naive.)
  5. Let me say this yet another way: This is not a thesis, not journalism and not Wikipedia. There is no reason to be objective or fairly present all sides and opinions. It is often not even useful to include all sides of your own opinions. For instance, many that have read my book may be surprised to learn that at my current work I use Microsoft Windows and Office and produce proprietary Symbian applications, and guess what, in real life I actually like my work. (Of course eventually I will probably want to work with Open Source stuff, no doubt about it.)
  6. Write about positive things: Did you notice SCO is not mentioned once in Open Life 1.0? The SCO litigation was supposedly a big issue when I was writing Open Life 1.0, but in my opinion those lowly scums are not worthy of my book! Talking about negative things - even if it's just to point out how wrong it/they are - usually creates a negative atmosphere in general, and you are the one who loses.
  7. One author illusion: Try to maintain an illusion that the book is being written by only one author. What I mean is, if in some chapter "me" says I like chocolate, "me" cannot dislike chocolate in the next chapter. So try to see what the others are writing and be cohesive.
  8. As a corollary of the above: If you are writing about yourself, say how you succeeded to submit a device driver into the Linux kernel, you would write about yourself in third person, since the author of the book couldn't possibly be a superman who does all the things told about in the book. The "one author" is just some guy who is following Open Source events on LWN and other places, he's not the topic of the book.
  9. Not a history book: Open Life is not a history book. There is no need to present things in chronological order. (On the contrary, see "Getting from A to B" below.)
  10. Dependencies: Also try to keep an eye on how later chapters of the book follow from the previous ones. For instance, after first introducing "Richard Stallman", we may later just call him "Stallman" or "RMS" and an author of a later chapter may choose to take for granted that readers now know he used to live in his office. But: Then a person editing the part that introduces "Richard Stallman" must be very careful when editing that part of the book, so as not remove any of the information later chapters depend on. We may need to develop a separate system for keeping track of these dependencies.

How to write a good story

For all you nerds out there, go and read The Poetics of Aristotle. I'm not kidding! This is the authoritative book on storytelling, even today compulsory reading for all writers and actors. All Hollywood movies still follow this schema.

Those of you who don't want to read anything written by an ancient greek philosopher, here is a short summary:

  • In every story, there is a beginning, a middle and an end.

Yup, it's that easy. Ok, so Aristotle has some more to say, but this is the gist of it. (Spoiler warning: As I said, Hollywood movies really do follow this format. Reading Poetics will probably spoil about half of your future movie experiences, since after watching 5 minutes of the beginning, you will know the ending of the movie. The middle is just filling, you wouldn't pay 10€ for the movie if it was only the beginning and an end.)

The beginning

So consider as an example the chapter about freeing the InterBase/FireBird database. It starts with the story of how the Borland management changed the company name every couple of months. Now, it is important to realise, that to tell the story of InterBase/FireBird, the name of the company is completely irrelevant. So why tell it? The purpose of those sentences is to lead with a story that makes it clear to the reader that we are now dealing with a company being lead by a bunch of incompetent idiots for managers. But instead of saying it directly, we tell it with a silly story illustrative of the silly managers. (And it doesn't hurt that it is a funny story in itself, and also illustrative of the crazy years in 1999-2001. I just want to stress that this is not the primary reason why that chapter starts with this story.)

So, having established that Borland was lead by incompetent managers, we are done with the beginning part of the story. It establishes the setting in which the subsequent events of the InterBase database are more colorful and make more sense, than if the author had just gone directly to the point.

As another example, consider the book or movie Lord of The Rings. (I only saw the movie. I know, not much of a nerd am I...) Why is it, that in a tight spot, Gandalf can hit the enemies with a lightning bolt, but Frodo cannot? I mean, it is a fairy tale, there is no reason Frodo too couldn't have magical powers?

The reason is, that it is established in the beginning, that in this world, Gandalf is a wizard and Frodo is not. Once you get past the beginning, this becomes an accepted fact and it would be silly for the audience to challenge it.

The middle

As I said, the middle is just filling leading up to the end.

If you are writing a tragedy, the middle is a sequence of events that inevitably lead up to the tragic end of the character through his own actions, even if the character himself does these actions exactly to prevent the tragedy. (Oidipus). If you are writing a comedy, well, it turns out the Aristotle manuscript on comedy has never been found. So you're screwed. Just kidding! Who needs Aristotle: Just watch a couple of Hollywood movies and do what they do.

Knowing the difference between a comedy and a tragedy is easy: A comedy has a happy ending, a tragedy a tragic ending. (So if you laugh at a movie, it is not necessarily a comedy. On the other hand, if it is a Hollywood production, it most probably is a comedy. In Hollywood even tragedies are eventually forced into happy endings, thus perverting them into comedies.)

The end

The end is the end. The main thing about the end is that there has to be a resolution. There has to be a reason why the story was told, there is now something different from how things were at the beginning. InterBase is Free Software and called FireBird. The guy gets to kiss the girl. The world is saved from aliens. (Notice how all three of those were comedies.) Typically also this resolution is embodied in the main characters of the story, they have grown as human beings as a result of it: They've become more open, better programmers, learned how to listen to and understand the girl (and then get to kiss her as a reward), overcome their fear of aliens.

The end also naturally reflects the beginning. After all, growth means that there has been a change between the beginning and the end. So for instance this text begins with saying that we are writing Open Life 2.0 and would you know, it also ends with that!

Getting from A to B

Open Life is a fact book. One purpose for the book to exist is to teach the reader about Open Source and openness in general. Having been a teacher for several years, let me give some hints here.

  1. Know your target audience and especially know their starting point.
  2. Now, you are going to teach them one new thing. Focus on that one new thing. One thing at a time.
  3. Figure out the simplest and fastest way to get everyone from their starting point to the new thing they are going to learn. Peal away everything that is unnecessary. As an example: It is great that kids in school learn many interesting new things. But let's face it, no one has ever complained about getting home a few minutes early!

So, in Open Life:

  1. Despite many readers being long time hackers, the lowest common denominator is very simple: Assume that the reader has used a (Windows) computer, email and www. Assume that they know about the existence of Linux and maybe Linus Torvalds. Don't assume that they know RMS, Bruce or Guido.
  2. Focus on the one thing you are trying to tell about.
  3. You are going to teach them one thing about openness, but you can only use the common assumptions that I listed above in (1), or things that have been previously introduced in the book. Remember: only one thing! If what you are trying to say requires people to learn many new things, you have a couple options. 1) Take those new things one at a time or 2) take a shortcut. I recommend taking a shortcut. Or you can also try to position your story later in the book, and hope that the pre-requisites you need will have appeared in the book by then.

Notice also, that since you are allowed to build on things introduced earlier in the book, you can take yourselves more liberties the further towards the end you get. If you are writing some of the first chapters though, KISS, KISS, KISS.

One of my main gripes about many hackers that write, is that they don't have this focus. The most common example are people who think that to introduce some basic thing about openness, you must first understand the difference between Free Software and Open Source, and that Linux is just the kernel (what is a kernel?) and that Richard Stallman is the greatest. At this point nobody is listening to you anymore! Sure, I know all of that, but I'm not a target audience of your story about openness. C'mon, I literally wrote a book on openness.

To give an example from my teaching days. One of the courses I used to teach was a 1 day course in JavaScript. In every course about half of the people had never programmed before. So how do you teach a programming language in one day? By keeping it simple! For instance, have you ever realised you only need 1 looping structure in a programming language? So why waste precious time (and confuse those poor minds) on teaching while(), for(), do while(), when you only need while(). That's what I did, and it always seemed to work well? Why teach about i++; when it is just another way of saying i = i + 1;? Those who knew programming, would have no problem using the other alternatives if they preferred, and those who were programming for the first time in their life, would be happy to make even one way work.

So take a shortcut or two, but get there!

Big Idea

At least I've often found it helpful to follow some Big Idea, a leading thought when making up a story. Even if the big idea isn't really obvious in the eventual result, it kind of helps you keep together while working. Consider an artist making abstracts sculptures for an example. He might think that those big rocks of different colors symbolise how we are all different as human beings - you think the nice colors look pretty in bright sunlight. You like the art, artist is happy.

Once I was editing a video of a childrens summer camp. There was one part were the kids are diving from the 5 meter platform. The sun is shining, there is laughter, screaming and splashing and I'm sure this will generate many warm and comfortable feelings when the kids will watch this with their parents some dark and cold winter night. So I had this big idea, that as part of that warm and comfortable feeling, we should make it clear to everyone, that nobody drowned while jumping into the water. To make that explicit, I extended each clip long enough so that the diving kid would surface, shake the water out of his hair and smile at his buddies.

Now, I must emphasize, that out of all the people who have seen this video, not once did someone come up to me and say: "Boy I was so relieved that nobody drowned when they were swimming." Of course not. But even so, following my big idea in editing gave the scene a slow, leisurly rhythm that actually mixed quite well with the summer music I had chosen for it. And I'm sure that subconsciously, many parents got a warm and comfortable feeling by seeing that their kids didn't drown.


I see that this now turned into a short lecture on writing. If you want to join in writing Open Life 2.0, but have not written a lot before, why not make this a real lecture and I'll give you a home excercise? Write something about Open Source, Creative Commons, or whatever. Preferably something you know about from where you live, for instance how your school installed Linux computers, or how you released your songs on the Internet. Actually, if somebody from Brasil is with us here, I'd love to hear about those Internet kiosks and all the other exciting things you are doing there. If you write a short story henrik.ingo [at] openlife.cc (for me), I could put it up here on the Open Life blog. And who knows, if we get many of these, they could become the base content of Open Life 2.0?


To submit a story either to my mailbox or directly here, it must be licensed with Creative Commons Attribution-ShareAlike license, or a more liberal license if you prefer.

hingo Sun, 2006-08-27 09:49