Yak-Shaving and Many Appreciations

[article]
Summary:

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.)

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

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.