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

Johanna Rothman's picture Johanna Rothman

Johanna Rothman, known as the “Pragmatic Manager,” helps organizational leaders see problems and risks in their product development. She helps them recognize potential “gotchas,” seize opportunities, and remove impediments. Johanna was the Agile 2009 conference chair. She is the technical editor for Agile Connection and the author of these books:

  • Manage Your Job Search
  • Hiring Geeks That Fit
  • Manage Your Project Portfolio: Increase Your Capacity and Finish More Projects
  • The 2008 Jolt Productivity award-winning Manage It! Your Guide to Modern, Pragmatic Project Management
  • Behind Closed Doors: Secrets of Great Management
  • Hiring the Best Knowledge Workers, Techies & Nerds: The Secrets and Science of Hiring Technical People

Johanna is working on a book about agile program management. She writes columns for Stickyminds.com and projectmanagementcom and blogs on her website, jrothman.com, as well on createadaptablelife.com.

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!

Upcoming Events

Nov 09
Nov 09
Apr 13
May 03