Sunday, September 09, 2007

How To Write, Part 1

In this ongoing series, I'll talk about how I develop and write stories. If you're interested in writing stories, getting tips and improving your style, etc., here are two great places to start.

First, browse the OWW, the Online Writing Workshop. It's mostly for SciFi, Fantasy and Horror writers but it contains lots of good advice and background references in the mailing list (ever needed to get some ideas on time travel stories? Who had already done what and how it worked out? Here is a good place to ask.

Next, have a look at the live journal of Joshua Palmatier. I have to admit that I haven't read any of his books but I greatly enjoyed his explanations, for example how scene, character and plot work together to build the complex immersion readers want to enjoy (and therefore, are willing to spend money and/or time on). I've rarely seen an explanation of these topics which was so easy to understand, so much fun to read and so helpful at the same time.


Next, you'll need a set of tools. Since I want to be able to write anywhere, I travel lightweight: jEdit, TreeLine and, since English isn't my native language, Office-Bibliothek. Being a seasoned software developer, I keep my stories in a Subversion repository. I do this for backup purposes and to be able to access them with a simple web browser for anywhere on the globe.


jEdit is a text editor written in Java. This means several things: It will run on Windows, Mac and Linux. If there is a computer where I am, chances are, I can use it. The keyboard mappings are the same. The menu structure is the same. It can do all I need and it can do it well.

Furthermore, since I write my stories in an XML dialect, I don't need a more complex text editor. Later, I'll convert the text to TeX from which I can generate PDF or DVI. Or I can use another small tool to convert the XML into HTML.

Why not use a more complex editor like Office or Frame Maker? Because it gets in the way. I want to write, I don't need a complex UI, software that crashes on me or gets in the way (do I have to say "paperclip"?).

The only drawback of jEdit is that the spell checker sucks. But if I cared, I could fix that. It's open source software.


If you write anything that goes beyond 30 pages, you'll eventually strangle yourself in the strands of information. What happened when? What was the name of this character? How old was she? Where was she born? Did I mention that place already?

An outliner is like a file explorer for information. To the left, you have a tree-like outline (hence the name) with characters, the time-line, places and other knowledge. On the right side, you can see the details.

There are more complex tools, suited better for writers, which allow to move around events on the time-line, which help to organize relations between characters, which contain name generators and such. For some reason, they are all Windows-only. For me, that means, I can't work at home because there, I have Linux.

I can waste as much time as my employer likes as long as they pay me by the hour. At home, I need to get work done.

TreeLine is the outliner of my choice since it runs on any OS and because it's written in Python which makes it simple to extend. For my purposes, I've added a "quicklink" extension which allows me to define keyword fields and then creates links to those entries in other texts automatically (for example, I get a link to the character description when I use its name in the time-line).

I'm using version 1.1.9. Don't mind the warning about "development version" on the download page, it's rock solid.


If you start to write, you'll find that you often repeat yourself. "He said, he said, he said." Don't worry too much about that, this will go away as you learn to use them words better. On the other hand, you don't have to make your life unnecessarily difficult. Get a thesaurus, a dictionary and a good spell checker.

My choice was Office-Bibliothek, again because it runs on Linux. The prices for the data files are in the same range what you would have to pay for the books and you get a much better user experience (less hefting a big tome around, searching is faster than you can type and you can search for words which are not in the index; try that with a paper book).


Subversion is a version control system, which will remember any change you ever made on your text. Not strictly necessary but it makes it much more simple to keep several versions (one at home, one at work, one on my palm and one on an usb stick) in sync, it automatically creates backups just in case I make a mistake and delete something I shouldn't have.


For many people, TeX is an anachronism. Why use a tool that expects you to write "this is a chapter" in your story when you can simply select the text in Word and chose "Chapter 1" in the toolbar? Well, because "simply" isn't so simple after all.

With tools like Word, OpenOffice and FrameMaker come a couple of price-tags which many people just have got used to and they don't question their motives anymore. First, we have the very real price tag. If you're not working with a pirate copy or one, for which you don't really have a license anymore, then you know, Word is not exactly cheap, even if you buy it alone. OpenOffice is free (as in freedom) and you just have to pay for the download but it's not available everywhere. Just imagine to try to talk the owner of a cyber cafe into installing OpenOffice for you so you can work an hour on your story.

Then, we have to issue of usability. I can work with Word and OpenOffice which means I can enter text and format it. Unfortunately, it will look like crap when it's printed. Both tools just have no idea what "beautiful" means and I frankly don't have the time or skill to teach them.

TeX, on the other hand, knows exactly how good (or bad) a text looks and it will even tell you so:

Underfull \hbox (badness 1789) in paragraph at lines 1041--1041
[]\T1/ptm/m/n/10 ^^PLook,^^Q the gen-eral started but she in-ter-rupted her:
[7] [8] [9] [10] [11] [12] [13] [14]
Underfull \hbox (badness 2073) in paragraph at lines 2165--2165
[]\T1/ptm/m/n/10 A smile split Forne's face. ^^PThank you, Ad-viser
[15] [16] [17] [18] [19] [20] [21] [22] [23] [24]
Underfull \hbox (badness 3148) in paragraph at lines 3705--3705
[]\T1/ptm/m/n/10 ^^PCertainly,^^Q an-swered the po-lite voice from above.
[25] (./haul05en.aux) )

Notice the "badness XYZ" warnings. They are just warnings. You can still print your text. It just won't look as good as it could. And in my humble opinion, a reader should not only get something that reads well but it should also look great. If you don't understand what I mean, print a page of text formatted with TeX and one page of text from any word processor and place them next to each other. Even if you don't know anything about font design and layout, the TeX version will make the other version want to roll up in its paper in shame.

Furthermore, since all markup (that's the information for the computer how it should treat a part of my text, i.e. if it's a heading, something someone says, a thought or whatever) is visible in the text, I never have to fight with the mouse to select just that part of my story that I want to select right now.

It's no accident that TeX is also the most stable software on this planet that I know of and that I use. The first version is from 1969 and the last update was December 2002. It's not dead, there is just nothing to improve anymore.


XML is both the greatest idea since ASCII and the worst nightmare. It is a great concept, it finally allows to store data in a format that anyone can read (Ever tried to open a document you wrote ten years ago?). Unfortunately, some things had to be added so even computers from the stone ages can still read it and some definitions make perfect sense but are hard to understand.

For my SciFi stories, I use a special XML dialect that I call "story". It won't validate but it's simple to transform into valid XML. Here is an example:

    * Surprise, Surprise

<<T I'll show them,>> he thought and jumped out of his hiding
place, waving his rifle like a madman. <<Y Back off or I'll

The muarhar<fn>Marauders of the south</fn> stopped dead, unsure
how big a threat he might be.


The part inside the content element is the meat of the story. It's a wiki-like format which allows me to write quickly (since I haven't found a single XML editor which would let me do that). The stuff between double pointed brackets encloses text that someone says or thinks. After that follows a single option character for thoughts (T), yelling (Y) or foreign language (F). In addition, I'm using a few XML elements like fn for footnotes, em for emphasis and q for quotes.

Note that I don't enclose paragraphs in p elements. In the beginning, I had a special key-mapping in jEdit to insert the empty element but I got rid of it. By adding a few simple rules to my "story-to-XML" converter, I made it add these by itself, freeing my fingers and eyes from such superfluous markup.

That's it. Now you just need a great story.


Jonathan said...

jEdit lets you pipe the text into an external command; perhaps you could write some macro to do this with aspell?

Aaron Digulla said...

There is already an aspell plugin which works pretty well. My issue with it is that I can't see the context of a wrong word. That makes it sometimes hard to guess what I was trying to say.

It's probably a small fix to have it scroll the main view to the current word and select it, I just never felt the big pressure to implement that.