Stoyan Stefanov

When in phase #2 of any writing process (the typing phase) you need minimal distractions. You need to just type away as frictionlessly as possible and lose no time at all in anything other than typing.

That's why MS Word (or any word processor really) is poorly suited for real typing, as oddly as this sounds. There's just too much UI going on, menus, options, toolbars. Even if you ignore and manage to hide these, it will causes damage with auto-correct and smart quotes in your code examples and so on. You don't need any of that. You don't even need to see that there's an option to make something bold or italics. Because that will make you think. Should I make this bold? Or maybe italics? All this takes your energy and causes you to type less.

Word is also terrible for writing code. It's simply not a code editor.

The best software for writing a computer book is simply your favorite code editor. It has everything you need, and everything you're used to. Tabs vs. 2 or 4 spaces and so on. Auto-complete. Your favorite macros and shortcuts that you normally use every day.

Your book is best written as plain text, as close to normal source code as possible.

Plain text

When I started typing away on JS4PHP, I just used TextMate which is what I use for coding anyway. I just wrote text. I thought of writing HTML initially and then use something to convert it but quickly reconsidered. Typing <code>var a = 1;</code> is too much typing. Opening and closing tags - meh.

The cool part about TextMate is that that is has auto-complete based on what you've typed already. So I got accustomed to write Ja, hit ESC and watch it complete to JavaScript

Knowing that there will be editing I figured the sloppier the original, the more rigorous the editing, so I just didn't bother to format almost at all. I couldn't help myself putting some ` though as in Here the function `foo()` is .... when dealing with code inline if a paragraph. Or some *really* and this is called a _closure_. You know, little markup pieces.

Once the first ugly draft was done, I started looking at how to convert this plaintext into something O'Reilly can use. I have heard of something called docbook or bookxml or something similar and suspected that O'Reilly supports it. So I though I have to take my plaintext and make it XML. But much to my surprise I learned that O'Reilly supports AsciiDoc.

AsciiDoc

AsciiDoc is an open source project that lets you write plain text with minimal markup and then generate a bunch of different outputs from the source.

For example `inline code` and *bold* and _italics_ and then some highlighted source code:

[source,js]
----------------------------------------------------------------------
// JS
var a = 1;
----------------------------------------------------------------------

[source,php]
----------------------------------------------------------------------
// php
$a = 1;
----------------------------------------------------------------------

Of course the [source] parts you add later, at editing time. While typing you just type the code.

Macros

Writing in your favorite code editor lets you come up with all kinds of macros and shortcuts.

Think about writing code MS Word. It's a pain. You write code and word mangles your "s and your 's. You undo. Copy the code, execute it somehow in a different program and/or terminal. See it has a syntax error. Fix it. Copy back to word. Then later decide to rename `foo` to something more informative. Repeat or risk publishing broken code.

In a code editor it's much easier, you write code in its natural environment. Then you can probably think of something to execute the code.

For me writing about JS and PHP it was two simple TextMate commands to run the code.

JavaScript:

#!/bin/bash
echo "$TM_SELECTED_TEXT" > ____.js
echo "<pre>"
echo `/usr/local/bin/node ____.js`

And PHP:

#!/bin/bash
php -r "{$TM_SELECTED_TEXT}"

I assigned shortcuts to these and then everytime I write some code in the book, I select it, press the shortcut and observe the result. Really quick feedback loop to fixing any errors.

In fact I have another JS TextMate command:

console.log('code: $TM_SELECTED_TEXT, result: ', $TM_SELECTED_TEXT);

Which makes it easier to spit out results.

Refactoring whole chapters and the whole book is also trivial when you deal with plain text (source code) in a source code editor.

Type all the things!

Removing friction out of typing is an enormous help. And writing a book in your favorite text editor and using something like AsciiDoc or markdown makes the process so much easier.

Another cool thing about O'Reilly specifically is that they give you an SVN repository where you check in your .asc files and images. Then they have a commit hook that generates a very production-like PDF (it's really asciidoc -> the weird book xml -> PDF) every time you commit changes, so you can see your creation formatted with all the O'Reilly styles, just like the real thing (barring some oddly positioned images, because of the autogeneration). The whole thing is not as immediate as edit-save-refresh web programming (it's edit-commit-wait-twitter-`svn up`-open PDF) but much better than the usual edit in Word -> send to Editor -> wait a month -> see the result

This entry was posted on Friday, June 8th, 2012 and is filed under books. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.