I am writing a book about agile program management. I have some portion of the first draft written. I don’t know how much, because I have not had any review. When I write, I can’t tell how much I’ve written until I have my first review. Then I will know how much I have that is good and how much is throw-away. (When I write a book, I have to write enough so my reviewers have enough context to review, but not so much that I’ve gone too far. I find it difficult to know how much to write before review.)
When the Prags turned down my book proposal (sniff, sniff), I had to decide what environment to use to write in. I decided to self-publish, to get the book out quickly. That means I want to be able to publish in all electronic formats and eventually in print form, too. Yes, I want to publish electronically first.
I am accustomed to seeing the book evolve as I write, so that was my first preference. I remembered a conversation from a conference a couple of years ago, and asked Neal Ford for a recommendation about writing environments. He suggested Asciidoc.
Asciidoc, or some other docbook-based toolset was my first choice. But I’m no longer a developer, so I have no idea how to install software that’s not packaged prettily, and asciidoc is not packaged prettily. I looked at the instructions. I can read them, but I don’t understand them.
I asked for help on the prag authors mailing list, and Andy Lester offered help. Andy suggested MacPorts, which is not what Asciidoc needs, so I got halfway through the installation and got stuck. Oops.
I contacted Tim Berglund, and he was helpful, but my partial installation was still in my way. His instructions did not match what I saw in my terminal window. Oh, boy.
I decided to use Scrivener. I wouldn’t be able to see the book as I wrote it, but I would be able to generate all formats at the end.
Then I saw Michael Nygard at Oredev this past week. I explained my quandry, and Michael offered to help. We spent 5, yes, five(!) hours on Monday yak-shaving, installing and uninstalling software. I could not have installed Asciidoc without him. I now have a working directory for the book I’m writing and a generic directory I can copy for other books. Yippee!
I am using git scribe to generate my book. Every time I make a change and gen a book, I can see all the formats. I can check all the formats as I proceed. I will be able to generate all electronic formats when I am done. I will be able to see the book in all formats as I write, so I can check the images as I write. This is a huge deal, because I have a ton of images. Ok, maybe to you 2-3 images per chapter is not a ton, but to me it is. That’s what I have now, and I don’t even know where I am in the book.
I could not have done this without the help of these many gentlemen.
Neal, I appreciate you for the suggestion of asciidoc. It is the tool I want to use.
Andy, I appreciate you for the suggestion of Macports as an install mechanism. You got me started.
Tim, I appreciate you for your encouragement and the suggestion of brew. That got me farther.
Michael, I appreciate you for helping me install asciidoc. That included explaining what we were doing as we proceeded, your handholding, and keyboard driving when you just couldn’t take it anymore. (I owe you hours of WordPress help when you decide you want it.) You made it possible for me to write this book the way I want to write it, and all the successive books I have planned. And, I enjoyed chatting with you, when we were downloading, compiling, installing and eating lunch. I liked being your client for five hours. You are a wonderful consultant.
For those of you who are wondering, yes, I have moved my files into the directory, and have already compiled two chapters. Ah, it is such a great feeling.
