Noel Rappin Writes Here

Self Publishing

Back to Mastering Ember

Self PublishingNoel Rappin2 Comments

Welcome back

This week I sort of broke ground on the book that will probably be called Master Space and Time with Ember. Here are some things I know or am reasonably sure about.

  • It's going to be pretty much a complete rewrite. I mean, some of the cranky rants might still be there, but all the technical content will be new. A new example application, too, though I'm still trying to figure out what that might be. (I've been using the time travel agency for years, it might be time to branch out. Later update: yep, it's going to be a different example, but obliquely inspired by the time travel idea.)
  • By complete rewrite, I mean: Ember 2.0 (eventually), Ember data 1.0. Ember CLI, ES 6, pod app structure, Mocha as a test library (probably). We will talk about creating a back end server.
  • In case it's not clear, this is going to be somewhat ambitious. It's going to be longer than the current book.
  • I'm also hoping for some clever design, both layout and structurally.
  • Beyond the basic Ember-y things, I want to include some bigger topics, definitely authentication, maybe integrating with d3. I'm open to suggestions.
  • I definitely want to focus on thinking Ember style, beyond just the mechanics of the objects and such.

Which brings us to pricing. I haven't worked out all the details, so subject to change. But it'll be something like this.

  • If you own the current Ember book, either on its own or as part of the entire MSTWJS bundle, you will get the version 2 book free for nothing. Mostly because I feel like I promised the update to all of you.
  • This means that buying the current ember book at $10 is going to be a hell of a bargain, because the base price will definitely be higher.
  • given my traditional bent toward underpricing, I doubt it will be as high as some of the other self-published books in this space.
  • if DPD implements it in time, I'd seriously consider variable pricing. I'm also considering something like Avdi's thing of just offering the book at two prices.
  • I'm also considering extra content, probably screencasts, either as a separate add on or possibly via Patreon.

And, timing. I'm hoping to start distributing early versions of the book, at least to current owners by the announced Ember 2.0 date of June 12. But I have no idea what state it'll be on by then.

Any questions?

All I Post These Days Is Status Updates

Self Publishing, mstjs, trddNoel RappinComment

Here’s where we are at the moment.

Master Space & Time With JavaScript: Ember

I think I may have finally gotten my head around the Ember release plans. My current understanding is that:

  • A 1.0 final release of core ember is imminent, possibly as soon as September 1.
  • There’s another major overhaul of Ember-data (the “jj-abrams” reboot branch), which will become the master branch sometime between now and the 35th of Octvember. In other words, who knows?

Which leaves me with the following plan:

  1. Once Ember 1.0 is released, I’ll start on a relatively minor revision of the book that will make sure it works with 1.0, allude to some new features, maybe talk about the Ember Inspector if I get ambitious.
  2. I actually don’t plan to add all that much new content, it’s already 108 pages, I doubt it will go above 130. (For reference, the Backbone book is 120, with longer code samples). I want to go through an authentication example. I may talk about components or more advanced view topics.
  3. Some of that is just going to wait until Ember-data gets sorted out, so I’m not rewriting the thing over and over.
  4. The 1.0-related release may be the one that triggers the price increase (based on length). We’ll see. But it’s coming.

You can buy Master Space and Time with JavaScript.

Trust-Driven Development

Work is proceeding on this a little faster. I think I have about 30 pages of text (it’s a little hard to tell because I have a lot of blank chapters adding pages).

I like what I have, but the organization is going to need work. Right now it’s really a set of interconnected essays about project topics (already written topics include points and velocity, user stories, iteration management, the introduction, and a couple of other topics.

The current plan is to start releasing actual text around WindyCityRails, September 12th. That triggers the price increase from $15 to $20, but I’ll probably soften the blow with a promotion over WindyCityRails.

If it’s not ready then, plan B is the same thing but over Ruby DCamp two weeks later.

You can buy Trust-Driven Development.

And another thing…

Weird as it may sound, this represents me trying to clear the decks because a new project has come up. It’s not official yet, and it’ll get its own blog post when it is.

Status Update

Self Publishing, mstjs, self promotionNoel RappinComment

It’s been well over a month since the last official update to Master Space and Time with JavaScript, and since I was hoping to get updates out more-or-less weekly, it’s probably a good idea to check in and let you know what’s going on. (Could be worse, though, I’m still hoping to post my top 10 books I read list. From 2011.)

All of the MSTWJS customers out there have been either very patient in waiting for the next update, or you are completely disengaged. Personally, I’m choosing to assume patient.

I am continuing to work on the book, it’s just slowed down quite a bit. The next update will most likely be sometime after RailsConf — ideally sometime in the week or so following. So by, say, May 10th. I post this date publicly to increase the chance that I’ll actually hit it.

There are a few reasons why the book’s progress has slowed.

To some extent, it’s a deliberate slowdown so I don’t have to rewrite the thing a dozen times. Yes, Ember is in an API freeze, but they are still adding new things that preserve compatibility, and Ember-data is decidedly not in an API freeze. Just in the last week or so, integration testing tools are starting to emerge — see this discussion for details. Honestly, the fact that I had to throw my hands up over integration testing in the last update was very disappointing, and I’d very much like to get that working in the example.

There’s also been some fumbling about what I want to cover in the rest of the book and how I want to get there. This one, I think I’m getting a handle on.

I also got busy. For example, I’ve been starting this weekly sort-of-screecast series for Table XI called XI to eye. I’ve never done anything like it, but I’m pleased with how this is going. There are five so far, you can see them all at Please do check them out.

I’m also doing two sessions at RailsConf — a normal session comparing rich client MVC with the 37Signals Basecamp approach and an intro track session on testing complex systems. More on those next week, but I’m excited for both of them.

There’s also been some laziness, and some lack of momentum caused by the combination of the previous points.

Still, hoping that this will move a little more rapidly in May — we’re now coming on the two-year anniversary of me starting the project (though I suppose I’d be done if I hadn’t decided to pick up Ember as a topic), and I’m certainly ready to move on. (I have some idea what my upcoming writing projects will be, just not sure which one I want to tackle next.

Thanks for your patience, if you are enjoying the book more will be coming — there will also be another errata catch up on the first three books. Please do help spread the word, or maybe buy it yourself.

Announcing Ember! Master Space and Time With JavaScript Book 4

JavaScript, Self PublishingNoel Rappin6 Comments

You have no idea how happy I am to announce that Book 4 of Master Space and Time with JavaScript: Ember is now on sale. You can buy it at /mstwjs

It’s not done, of course. But it’s off to a good start, and I think it’s going to be great. Here’s the state of the world:

  • Release 1 of the Ember book is $7, just like its recent siblings. The four book bundle is still $15.

  • Release 1 is about 20 pages of content (plus the same intro, acknowledgments, and so on). It covers setting up the Time Travel app with an Ember front end, then the basic concepts involved in getting data from the server, displaying it to the browser and responding to actions. We basically end at a chapter break, so it’s a contained example, though obviously the rest of the book will take it farther.

  • The code is written against Ember 1.0pre4, which means its current as of yesterday.

  • Unlike some of the other betas, this one has been reviewed by a few people, including people who know more about Ember than I do, so I’m pretty happy with how it’s going so far.

  • We don’t cover testing yet (in part because the framework does so much that there isn’t much logic to test yet). It’s coming, though. Trust me.

  • The plan is for basically weekly releases until done.

  • I don’t know how long this is going to get — to some extent it’s going to depend on the reception, more sales = more encouragement to write. It will be at least in the 100is page range as the previous books. If it gets much longer than that, I may raise the price at that time.

That’s the scoop. Buy it: /mstwjs, enjoy it, spread the word.


State of My Stuff, January, 2013

Self Publishing, self promotionNoel RappinComment

The state of the Noel Rappin publishing — I can use the word “empire”, right?

MSTWJS 3: Backbone

Master Space and Time With JavaScript, Book 3: Backbone is draft complete as of today’s release except for a page or so of summary at the end, which I will probably wait to write until the Ember chapter is complete.

The next release will be an edit pass, to clean up typos and bad sentences, smooth over the explanation, fix errata and generally polish stuff. I haven’t done any of this on the book yet, so it’s possible there will be some bigish changes depending on what I think is going on.

Any further releases will be errata and cleanup based.

MSTWJS 4: Ember

I’m starting to get actual questions about the Ember version.

In the wake of the Ember team getting their newest router API into master, and also updating a lot of their documentation, I’ve broken ground on this one and am moving forward.

I will release this in a pretty early state, I imagine, and continue with the weekly updates until it’s through, which I expect will be on the order of ten weeks. Ish.

I have two criteria for the initial release. The first is that I need the example in the book to go far enough to display some things on the screen and show off some event and property processing. Secondly, I have a couple of people who have volunteered to sanity check the book, and I’d like at least one of them to sign off on it before anything insane I write is exposed to the general public. So, optimistically, Jan 14, but maybe a week or two after.

MSTWJS 1 and 2

I do have some standing errata that have been reporting. I would expect not to see an actual update until after the Ember book is on sale, not least because then the update email can be used to tell all the free book one customers that the Ember book exists.

Next Projects

So, I do know what my next project is going to be, I’m planning on self publishing it. It’ll be Ruby and testing based, but I don’t plan to start on it until after the Ember book is out in the wild. I came up with an outline while I was waiting for the Ember team, but now that I they look solid, I want to get that out first.

Master Space And Time Status Update

Self Publishing, mstjsNoel RappinComment

Here’s a quick status update on Master Space and Time With JavaScript, book 3…

Short version: expect an early beta of about 1/3 of the book to be out in about a week.

Longer version:

Work is proceeding steadily, the current draft of just hit 30 pages toward a target of around 90, though about 10 of that is the same intro and outro that the other books have, so it’s more like 20 pages toward a target of 80.

The structure of Book 3 is one chapter on replacing the existing app homepage with a very simple Backbone clone, then another chapter building a different page using Backbone that has more events and more complexity, then a third chapter talking about communication between Backbone and the server, and anything else that comes up. The exact division between the second and third chapters may change.

I will release the first beta when the first chapter is draft complete — this will be rougher than the other books because it hasn’t gone through rounds of review and editing, but I like how it’s going. I also need to clear through reported errata on the first two books, and probably clean up the landing page in expectation of doing another marketing push.

Thanks for being patient and for your great feedback.

Oh, and you can still buy it!

How's it Going? MSTWJS Edition

Self Publishing, mstjs, self promotionNoel RappinComment

And now for a more inside-baseball post about how the self-publishing aspects of Master Space and Time With JavaScript are going. Did you know you can buy it?

Short answer: Pretty well, though I could always have done better. Still unclear how this will work over the long haul.

At this point, the book has been on sale for 10 days, plus the pre-sale to people who were on the mailing list. It’s clear that the initial burst of traffic from incoming links is slowing down, and I’m now entering the longer struggle to get people interested — not completely sure how to do that.

Anyway, a few disconnected points about the process so far

One of the big things I miss about a larger publisher is the marketing reach. That said, there’s something really nice about how people feel a little bit of ownership concerning self-published projects that they like. I’ve gotten a couple of very nice copy-edit runs, for example.

I’ve generally been lucky in reviews (notable exception: the two-star review of RTP on Amazon that I check out whenever my Impostor’s Syndrome feels insufficiently pronounced…), and so far, the people who have commented on the books where I can see them have been positive.

I can be a little transparent with numbers. As I type this, traffic is still about double the level that I had generated in the past on days that I posted to the blog, and much, much higher than the ambient level of traffic when I hadn’t been posting.

Over the course of the ten days, about one in six people that have hit the landing page at /mstwjs and aliases convert to either the free version or one of the paid versions. Low day was 12%, high day was just under 23%. There doesn’t seem to be a consistent trend between traffic and conversion rate.

So that’s about one in six doing anything, of those that do choose, about one in six or so actually bite on one of the paid versions. So that’s a paid conversion rate in the 2 - 3% range. That rate seems to be slightly negatively correlated with traffic, which is actually in line with what I would expect.

As for the pricing strategy, which I thought was so clever… So far, there have only been a very few people buying book 2 at the $7 level — most purchases have been of the whole book at $15. I’m not planning on changing the pricing (beyond my already-stated plan to raise the $15 when Book 3 gets near-final). I want to see how this looks when there are more individual books for sale. But there’s a good chance this means that I outsmarted myself, and probably could have priced a little higher.

So far, as best as I can tell, under 3% of people who originally downloaded the free version came back to upgrade. That seems very low, but it might be higher — the way I’m counting this, if somebody gave me a bogus email for their freebie, I wouldn’t track it as an upgrade. Also, I assume this number goes up a touch as people read the book and as upgrade reminders go out. Still, as it stands, it’s not a great data point for the “give away free stuff to increase sales” school of internet marketing.

Over the course of the ten days, the number one referrer, by far, was Peter Cooper’s JavaScript Weekly email newsletter. It’s the biggest by about a factor of three over the next highest measurable referrer. Next up was Twitter, and I think the highest link out of those came from JavaScript daily, and I think the second one was from my feed. It’s really hard to track those for sure, though. Third was Google Reader, though I think that was mostly blog posts and not links to the landing page. Fourth was Reddit — my post there didn’t get much traffic, and fifth was the Ruby5 podcast and show notes. Rounding out the referrals so far is Mike Gunderloy’s Fresh Cup links, and then we also get some noise with internal referrals and things like Pocket, and the Ruby Rogues link, which just came out.

Another point of comparison is that MSTWJS sales are about 150% + of RTP sales over the first ten days. That’s less impressive than it sounds, I really struggled to get traction with RTP after the initial burst. (That’s the paid number for MSTWJS, and it includes the pre-sale to the list). RTP had a free section as well, and I don’t have any stats on how often that was downloaded, but since it was just a link and not a shopping cart, I think it was pretty high.

That’s where we are — I hope that those of you that bought or downloaded the book are enjoying it, and if you are hoping to do your own self-publishing project, I hope this information is helpful.

Oh, and the book is still on sale.

The Origin of Master Space and Time With JavaScript

Self Publishing, mstjs, self promotionNoel RappinComment

I have a new book, Master Space and Time With JavaSript. You can buy it.

Here’s the secret origin.

This all started over a year ago. Rails Test Prescriptions had been complete for a few months, and I was getting a little antsy to take on a new project.

But what? I wanted it to be a project where I would learn something, and I wanted it to be something where I had a particular perspective to offer.

A couple of recent experiences pushed me toward view-level coding in general, and JavaScript in particular. About then, for the first time in a while, I worked on a project that had a reasonably serious JavaScript front-end on a team small enough that I was contributing some of the JavaScript.

It quickly became clear to me that JavaScript coding had changed dramatically, not just from my first pass at it (warning clients away from it circa 2000), or my second pass (avoiding it with RJS circa 2008). The tools were better, the idioms had changed, and the expectation was that future web applications would need to handle this stuff very well.

I was also working with a new Obtiva apprentice, who wanted to build a very JavaScript-heavy site, but didn’t really know much JavaScript. In searching for books to point him to, it seemed to me like there was an underserved part of the market, not for total beginners, not a description of a particular library, not a pronouncement from On High about The Right Way To Do Things, but a practical guide to writing and testing modern JavaScript to do cool stuff.

Which is what I set about to write. My original proposal for this book may well be one of the best pages of text I’ve ever written.

And yadda, yadda, yadda, here we are.

I knew I wanted the book to build up on a single web application example — I’ve always liked that style, even though it can be a pain in the neck to structure. I also knew that I wanted to have a lot of testing in the book. Not only is writing about testing in JavaScript something that seems pretty needed, it also felt like a perspective where I actually might have useful things to say. Plus, I had used the largely-test-first style of writing before (in the Wrox book), which I’m sure was appreciated by all three of the people who bought it. I thought I could do it again.

The idea of taking an application with no JavaScript and adding JavaScript features seemed like a good hook. I’d used the Time Travel Adventures travel agency before (for my testing legacy code workshop), and the idea of a time-traveling client who was confused about what modern web sites needed seemed like a suitably silly hook. (In the first draft, the client was named Emmett Brown, but I was guided away from using that name directly, hence the client becomes the mysterious Doctor What.)

And I was off…

Here’s what you get in the books.

Book 1 is largely concerned with a particular simple-seeming request: add a show/hide toggle link to each trip on the home page. Although this is simple, it actually winds up touching a fair amount of jQuery — using selectors to find elements, binding events, and manipulating element pieces.

We build up this toggle thing in a few stages. First is a quick pass writing a simple version of the toggle functionality test-first. The goal here is a sense of what a test-driven process looks like in JavaScript, plus the basics of how Jasmine and jQuery can be brought to bear to write the feature. It’s basically the book equivalent of “fast to green”. We solve the problem with the understanding that we’ll clean up the details later.

Then we go back with two more chapters that go more in-depth on first Jasmine, then jQuery. In these chapters, we don’t add new features as much as describe the library features that supported what we did and explore related functionality.

The final chapter of Part 1 covers the JavaScript object model and why it is confusing if you come to JavaScript from a more traditional Object-Oriented language. By the end of it, we’ve used the module pattern to build the most over-designed show/hide toggle ever. I’ve had some experience doing workshops based on the material in this chapter, and it seems like even people who have been doing JavaScript for a while get something new out of it.

And that’s Book 1. It’s available for the low, low price of zero dollars and zero cents. Worth every penny.

Book 2 is mostly about apply and extend. The first chapter is about building up an widget that combines an autocomplete text input with a list of currently chosen items. Test-first, of course. The we throw some Ajax in the mix, extending our already gold-plated toggler with the ability to get data from a server. This also gives us an excuse to talk about Jasmine spies. Finally, we build up a rating widget, with the clickable stars and a histogram and stuff, which lets us talk about JSON and Mustache. There’s also a small, slightly out of date bit on the Chrome developer tools. I’ll catch up on that at some point.

Book 2 is a mere $7.

Or you can get Books 1 & 2, Plus books 3 & 4 when they come out for $15. That $15 is a temporary price, and will go up when Book 3 gets closer to completion.

Book 3 is going to be about Backbone. I know the structure of most of it — first, we’ll recreate the front page using a Backbone structure. Next, we’ll build a buy page that allows you to make several calculations about differing trip purchase options on the client. Not sure about the last part, it will definitely include communicating back to the server, probably something else.

Book 3 is going to start appearing on the site in a couple of weeks, and will probably be draft complete by the end of September.

Book 4 will cover Ember.js. I’m not sure yet what we’ll build, though I want it to be a new part of the site, and not a recreation of the same things we do in Backbone. I’m hoping that Book 4 will be out by the end of 2012.

Oh — the title. I had a list of two word titles that were like POWERWORD JavaScript, but all of them were either taken, sounded ridiculously stentorian to me, or both. The original proposal titles were “Getting Things Done in JavaScript”, which nobody liked, or “JavaScript for People who Hate JavaScript”, which nobody liked (see the pattern).

I had Master Space and Time with JavaScript on my list as kind of a joke — a reference to the Time Travel conceit in the book. Plus I liked that it sounded like a pulp adventure novel, and would lend itself to a cover easily. I know it’s not the, like, SEO favorite title, but I’m hoping that people won’t forget it once they hear it.

The cover, by the way, is my own design, and I like it considerably more than many of the other things I’ve designed. (I’m also pretty happy with the PDF layout…) I think the cover particularly works well at thumbnail size, so you can see the difference between the individual books easily.

That’s the story. Hope you like it. Buy it!, or tell all your friends (Twitter hashtag #mstwjs).


Master Space And Time Release Plan

Self Publishing, mstjsNoel RappinComment

There is a plan.

It goes like this:

Master Space and Time With JavaScript will be split into four parts.

Part one and part two will be available sometime in July. I’d say July 1st, but I’ll still be in Scotland. It’d be sooner, but there are still logistics to be managed around the actual layout of the book and getting the payment gateway in order. Plus, I need to actually finish the text.

Part one is an introduction to Jasmine, jQuery, and the JavaScript object model. It will be available for free.

Part two will be more advanced jQuery, Jasmine, and JavaScript examples. It will be available for, most likely, $7.

Each part will be on the order of 50 - 75 PDF pages. The exact split between the two parts will depend on the final page count of the chapters.

You will also have the option to pre-purchase the entire book — that’s an immediate download of parts one and two, and an eventual update with parts three and four. That bundle will most likely be $15. I’m not sure yet how long that option will remain available.

Part three, will cover Backbone.js. It will come out something like four to six weeks after parts one and two. Part three will also be $7.

Part four, which will cover Ember.js, will come out some time in the future, same deal.

There are two reasons why the Ember.js part might take a few months. One is that I’m still kind of waiting for Ember.js to settle.

But the main reason is that I plan on doing other things.

More mini-books, in the 30-75 page range, for $5 to $10 each. I’m going to do at least one, maybe two, before the Ember.js part. (Yes, I’ll say what they are. Eventually).

And that’s the real plan: an outlet for me to release these mini-books on a regular basis. To write these ideas that I have that aren’t quite long enough for full books.

I’m excited about this. I have a few topics I’ve wanted to write about for a long time, and this is way for me to get these out to people who I think will find them useful, interesting, and fun.

A couple of other logistical things:

  • In case it’s not clear, all releases will be digital with PDF, ePub, Mobi, maybe HTML. iBooks Author is a possibility, but probably not in the immediate future.
  • I would update previous books to correct errors and typos and that kind of thing.
  • I’d like to have some way to offer something like a subscription. I need to find out what the payment tool I’ll be using makes possible.
  • I’ll probably have some sort of umbrella name for the series, but I don’t know what it will be yet.

I think this is a good plan. I hope you agree. I’d love to hear your thoughts, and if you want to get an email when the first two parts are available, please fill out the interest form

Self-Publishing Workflow Update

Self Publishing, mstjsNoel RappinComment

Next up on the Master Space and Time With JavaScript status report is the workflow that takes my words and turns them into a PDF. And an HTML file. And an ePub. And don’t forget Kindle.

As you can imagine, this is something of a minefield, although there are a lot more tools available than there were three years ago when I did this the last time — here’s an overview of the process I used then. That article talks about the process that I used on Rails Test Prescriptions for as long as it was self-published.

Things have gotten more complicated. Most obviously, there are more devices and formats to support. The Kindle’s mobi format and ePub are different, and every ePub device has its own quirks. On the plus side, there are a lot more tools and libraries available than there were, though figuring out what they all do is a challenge in itself. Plus, a lot of the existing tools produce documents that are, well, kind of dull-looking, especially noticeable in the PDF versions. (If you are a self-publishing author, I don’t mean you, your stuff looks great. Those other people, though… can you believe them?)

Over the last few years, I’ve gotten addicted to being able to sort of see what the text looks like all laid out fancy and the like. So it was important to me to get at least the semblance of a tool chain in place before I started rewriting in earnest, not least because I needed to figure out what format the text was going to be.

Here’s what I’ve got. It starts with Markdown, because Markdown is pretty simple, I’ve been using it for years, and there are like a jillion editors that support it. Because I’m using Markdown, I’m also experimenting with writing the book in a more writerly editor like Byword, rather than a programmer editor like Sublime. In theory, this will make the book less… I don’t know, less programmerish, or less sublime? Dunno, but right now, I’m enjoying the change of scenery.

Then it starts to get complicated. There are multiple implementations of Markdown or Markdown-like libraries, and they all are subtly different. Right now, I’m using Multi-Markdown, since it has footnotes and cross-references, though there’s some possibility I’d switch at some point in the future. (I love footnotes, and I’d add one here, but I don’t think this blog engine uses a version of Markdown with footnotes.)

Markdown’s weakness is that it’s hard to specify custom styles or HTML classes. I’m working around that by running my Markdown text through a pre-processor where I can put in some custom directives. I can, for example, write:

:title A Sidebar
The sidebar content goes here

The pre-processor catches that, and converts the code into some specially styled HTML. (Yes, I’ll be open-sourcing the tool at some point in the future.)

I’ve also added something that I’ve wanted for a long time, namely the ability to insert code from a file at an arbitrary branch in a git repository, meaning that I can show code from multiple successive versions of the same file just by having them in different git branches. Meaning I can distribute the sample code in a git repository and have it not look too awkward.

I also have the ability to post-process Markdown’s HTML, which I think I’m eventually going to need to reconcile the rest of the tools.

Once I have the converted HTML, I need to generate e-book files. For PDF, I’m going back to using PrinceXML. There’s a lot of things I like about this tool. For one, it has a lot of the features that you would normally associate with actual books, like section numbering, footnotes, cross references, and page headers and footers. I think it produces nice-looking files, and its controllable with CSS, a technology that I (mostly) understand, so it’s easy and fun to tinker with.

I didn’t have any existing tools for ePub or Mobi, so I looked at somebody who I thought was creating pretty nice files, specifically Avdi Grimm, who did a pretty great job with the Objects on Rails ebooks. Avdi created his own tool called OrgPress, and for ePub and Mobi, he uses the command line interface to Calibre. Even though OrgPress uses Emacs Org Mode, Make, and Awk — three tools that, to put it mildly, I feel no particular pull to tinker in — I was able to take advantage of Avdi’s hard-fought war with Calibre to get a set of command line flags that basically work, though I’m going to have to tweak them a bit before they are salable. I’m also looking at Rpub, since it’s in Ruby.

One nice side effect of all these tools is that it’s easy for me to have an almost all iPad workflow — I turn on watchr on the laptop, write using Byword on the iPad, and when Dropbox syncs the file, the ebooks are all updated, and I can view them on the iPad via Dropbox. Not bad.

I know this isn’t done yet. For one thing, I suspect that Multimarkdown and PrinceXML are going to disagree on the format for a footnote, and I’m probably going to have to referee. Later note: it’s worse then that… Multimarkdown’s footnote format actually crashes the Mac Adobe and Nook ePub readers, though that seems to be a bug on their end, and it does work in iBooks.

I’m eventually going to need custom styles for each format — the sidebar CSS that looks great in PDF looks awful in iBooks. And I’ll need a cover.

And, you know, content.

May 9, 2012: The Random Link Post Returns

JavaScript, Music, RSpec, Ruby, Self PublishingNoel RappinComment

And now, the return of the semi-occasional link post. I’m going to try to do this at least once a week, but who knows.

If you are writing JavaScript, you should be looking at Justin Searls and his JavaScript testing tools. Justin posted the slides for what looks like a great talk on JavaScript testing. These slides made me happy.

In random media sales, the audio book of World War Z is on sale for a mere six bucks.

A couple of Ruby posts. Steve Klabnik argues that merely splitting code into modules doesn’t reduce complexity. Instead he argues that you need encapsulation. I think splitting code is probably better than nothing, but not a lot better.

Meanwhile, Avdi Grimm describes the Ruby idiom for type conversion which I have to admit, I never thought of as an idiom before.

In a story that I think of as a cautionary tale about pricing and value, the LA Times writes about the history of American Airlines customers who bought unlimited tickets. And then, you know, they used them, unlimitedly.

I always like to see plucky programmers trying to self-publish books about testing. So I’m glad that Aaron Sumner is LeanPubbing a book on testing Rails and RSpec. Good luck, Aaron!

Pretty much everybody who blogs or writes or tries to explain things to people should read this XKCD

Finally, a random music recommendation. I don’t recommend music much, but I do have a weakness for lyric-heavy, earnest, catchy music. Which brings me to the Lisps and their recent musical project Futurity. The musical is a Steampunky kind of thing that concerns a Civil War vet who tries to build a “Steam Brain” with the help of Ada Lovelace. It’s clever and I like it. Album Link. On a similar vein, their song Singluarity from their previous album Are We At The Movies.

Writing Tools

Self PublishingNoel RappinComment

I hate Microsoft Word. That’s not the only thing that caused me to want to do this book this way, but it’s in the top five.

That’s what we in the writing biz call “a grabber”. Right? Feeling grabbed?

The usual complaints about Word aside — it’s bloated, the UI is hopelessly busy, managing complicated layouts is nigh impossible… um, it’s possible I’m not leaving those complaints completely aside.

Let me try again. On top of the usual complaints about Word, it’s also spectacularly unsuited to the kind of technical writing that I’ve been asked to do using it.

My standard line about Word, which I’ve been using for about eight years, is that it was built and optimized for creation of the four-page office memo. Something short, with a small number of consistent styles that rarely, if ever, need to be specialized or changed. And without much in the way of complex layout.

Here’s how Word gets used. The publisher has a template with dozens of different styles (Wrox’s template had more than 80 styles with descriptive names like “TX” or “NL2”). Each chapter file is fifteen to forty-five pages. Nearly every paragraph has to have character stylings changed inside it for code literals or some such, and there’s not as much consistency as to what order styles come in (code paragraphs can pop in anywhere, for example). As a result, technical writing using Word tends to devolve into long fights over the styling of various elements.

On the publisher’s side, the Word documents are (I think) converted internally to whatever more powerful publishing software they use, which is why the writer needs to use the publisher’s style template. For what it’s worth, I think the publishers keep using Word because of a) Word’s change tracking facilities, extensively used during the production and editing phase, b) it’s perceived as something that everybody will have, which I’d guess is a surprise to Linux-based authors, and c) there is a large sunk investment in the scripts that convert the document files.

Anyway, when I started working on the wxPython book, Patrick and Robin had worked out a system where we wrote the book in reStructured Text. Patrick had written a script to convert the text to Open Office format using the publisher styling, and then we manually saved those files as Word files to hand in. Writing in plain text using a text editor was much easier and faster. Among other advantages, it was easier to share code across our different OSes, and it was easy to use source control for the book text. Down side was that the conversion to OO was a bit wonky, and once we turned in the final chapters for review, we were basically stuck with Word throughout the review and publishing process. Which lasted about a year, but that’s another story…

Since then, I’ve always asked what tools the publisher uses throughout any of the projects that I’ve pursued. And I’ve looked longingly at the publishers that I know use text-based tool setups (most notably Pragmatic). The IBM articles use an XML markup that I can write in a text editor, and publish locally, but with a pretty heavy markup.

In creating what I use for this book, I was very fortunate to get a pointer to the scripts used by Carlos Brando for the What’s New In Rails Books. This was a great place to start in creating a work flow. The flow looks like this

  1. The initial text is written using Markdown, with occasional raw HTML because some of the formatting requires specific CSS classes. I’m comfortable with Markdown and can write it pretty quickly. And I get to use TextMate or any other editor I might want in the future.
  2. Since it’s text, I can easily use git for version control locally on my machine, and have a complete record of all my changes. (I also use Mozy for offsite backup of the whole deal).
  3. A Ruby script converts the Markdown chapters to HTML with some processing, most notably parsing the code segments using CodeRay.
  4. A script converts the HTML to PDF with PrinceXML and a CSS style sheet with a couple of extensions to support page layouts, footnote counting, and the like. I like this because I (mostly) understand the CSS, and I find it easy to manipulate.

I’m finding this process to be quite flexible, easy to work with, and allowing me a readable text view and quick visualization of the final layout. For example, it took me about an hour and a half to make the changes between the first version and second version of the tutorial, and that includes figuring out how to incorporate CodeRay.

I’m happy with it so far — it’s much more pleasant to work with than any other of the books I’ve worked on.