Snook.ca

My Notes on Writing an E-book

jonathan@snook.ca (Jonathan Snook) — Thu, 09 Feb 2012 00:41:23 PST

So, yeah. I wrote an e-book. It has been an interesting experience and I thought I'd share a few random thoughts on how things have gone so far.

Backwards

When I first started down the path of writing the SMACSS e-book, I had intended it to be either an e-book or a printed book. After months of writing and not getting enough written, I released what I wrote as a web site. A free web site at that. However, I also released it with the intention of continually adding new content to it until I had reached a point where I had a "finished product".

Right away, though, many people asked for the site in an e-book and even a printed format. With my intention to add more content, a printed format just wasn't (and still isn't) a practical option. However, an e-book could be created and updated over time. And so I started down the path of converting the HTML content into other formats.

Knowing my preference, I decided to try and put together the e-book in different formats, since each format has its own pros and cons. I did PDF, ePub, and mobi.

Mobi is the format used on the Kindle and other e-ink readers. It lacks a lot of control over formatting and was the lowest common denominator. ePub is the format that Apple uses and was a format that I wanted to push the limits on—even if maybe just a little bit. Lastly, I also went with PDF, which has great support across most platforms.

Once I stop writing new content, I may very well do a print version, too. This feels rather backwards from how a publisher would normally do it: print to e-book to free. I went from free to e-book to (maybe one day) print.

Working in ePub

Trying to find accurate and up-to-date information on creating an ePub file targetted for iOS proved to be surprisingly difficult. Searches revealed information that was often a few years old and targetting older versions of the spec. Apple also supports non-standard features like embedded audio and video. The problem was trying to figure out what some things wouldn't work.

The ePub format, if you're not familiar, is just a zip file with a bunch of XML and HTML content. The XML defines the assets and table of contents and the content itself is in an HTML format. I ended up using Sigil to expediate the conversion but discovered that Sigil sticks heavily to the spec. Embedding HTML5 video, for example, will get stripped out automatically without any clear messaging telling you that the application has done so. That was frustrating.

I was able to use font-face embedding, which I liked. It allowed me to maintain elements of the brand from the web site and bring them into the e-book. I was able to buy an extended license to embed Quatro Slab in the e-book.

Hand coding the files turned out to be a better solution, although I still find updating the table of contents XML a hassle.

Testing the ePub on my iPhone or iPad was somewhat straightforward. Just drop the ePub file into iTunes and sync it to the device. The problem is that the device caches information about the book so dropping in an updated file doesn't automatically update the book on the device with the latest version. Deleting from the device and deleting from iTunes and dragging the file back over may work. Sometimes. But not all the time. I never did find a reliable way to easy push new book updates to the device.

Working in Mobi

Short and sweet: with such limited functionality, I used Calibre to convert from the ePub version to the mobi version. I had a friend try it on the device and went with it as is. I didn't make any other changes to get the e-book prepared for the Kindle. It was this version that I ended up uploading to Amazon (which I'll talk about in a bit).

Working in PDF

I used Pages and manually copied all the content into it, setting up styles and managed the layout of the book manually. I think I used A4, which is unusually large. The next version of the PDF will likely use half-letter size. This turns out to be the same size as the A Book Apart series of books. If and when I go to print, the half-letter size should hopefully be easier to print.

Manually laying out the content is a chore and means that minor edits to the book have to be done in multiple places. I'm looking at some HTML to PDF options to make this step easier but so far, I haven't found anything that's perfect.

Working in DocBook

Wait, what? What is DocBook? Working in multiple formats, I longed for a way to build in a single format and then export into all of the other formats I needed quickly and easily. I chatted with folks at a couple different publishers and they said they used DocBook. It seemed like the way to go.

Unfortunately, I didn't like the HTML that was getting created. This would ultimately be the HTML code that would appear on SMACSS.com and in the ePub version (although I suspect nobody would have seen it there). Just having it on the web site meant that I was more particular about the output.

DocBook is an XML format and getting my content into the format was easy enough. Getting it out, however, was mired in DIV tags 4 or 5 levels deep. Not an example I wanted on my web site. The XML to HTML conversion happens with a set of premade XSL files. You can tailor your own XSL files to get the output that you wanted. However, after finding myself working for hours over the output of each element of code, I gave up.

If you didn't care about the HTML or were okay with the HTML the DocBook XSL generates for you then DocBook might be a good fit for you. For me? It definitely wasn't.

Publishing with Amazon

I decided to publish to Amazon as a way of possibly having people randomly come across the book who might not otherwise do so. The sales of the book on Amazon have done quite well, exceeding the number of $15 ebook sales through my own site. The reporting from Amazon's site isn't really the easiest for tallying up total sales on a daily basis. However, I'd estimate that I've sold almost 200 copies of the ebook through Amazon alone.

Amazon has different royalty points. If the book price is over $10 then you only get 35% from each sale. If the book price is under $10 then you have the option of 35% or 70%. What's confusing is that even though I chose the 70% option (and priced the book below the $10 threshold to ensure that I could), not every sale automatically results in 70% royalties. I must've missed some fine print somewhere because a third of e-books sold via Amazon US only got the 35% royalty.

One of the other downfalls with using Amazon is that you don't get access to any customer information. You don't know how they found your book or have any way of contacting them. This is okay if you're just doing the book and nothing else. But I have the workshop and potentially other things down the road that people may be interested in. I'll never know.

Why not Apple iBookstore or Nook?

Both Apple and Barnes and Noble require tax information to be supplied up front, which I didn't have. As a Canadian, this usually means filing for a special tax number that is filed with a W8BEN form. As an American-Canadian, I should actually be applying for a SSN and filing US taxes. Way more effort than I really wanted to put into it.

As I learned afterwards, Amazon has the same requirements. If you don't provide the information, it deducts a hefty portion off of the cheque it sends you. That I'm already selling it for less than money than I sell it on my web site and that I already lose 30-65% off the top for royalties makes this less than ideal.

Both Apple and Barnes and Noble also suffer the same problem that Amazon does: they take a considerable share of each sale and provide you no customer information in return.

Customer Contact

Before I launched the site, I set up a form to subscribe to a mailing list. I had approximately 500 people sign up. When I launched the HTML-only site, I sent a campaign to the list and then shuttered the list.

That was stupid.

As I began work on the e-book, I set up a new list and hoped that everybody who had subscribed before would resubscribe again. Thankfully, the subscriber count has climbed its way back up. Don't let people fool you: e-mail isn't dead. E-mail sent to people who want to receive it are very attentive. They'll click through. They'll read what you have to say. You have their attention.

Social Networks

I relied heavily on my Twitter stream to get the word out but people often miss a tweet. I have friends who still don't realize that I've written the e-book. Go figure.

But I also realized that I didn't take advantage of Facebook or Google+. I'm getting better. I'm trying to use the avenues that I have available to me. As I work on the workshops in addition to the extra content, I need to remember that not everybody hangs on my every word on Twitter.

Advertising

To put it bluntly: it has been a waste of time. If someone is successful with advertising, it's definitely not me. I spent nearly $1000 on advertising between Google AdWords and Fusion Ads (the very ads on this site) and while I got click throughs, few resulted in actual sales. Would a sustained ad have provided better results? Would someone who understands ad word targetting have done a better job? Maybe.

Are there other advertising avenues that I could try? Yes. I didn't try Facebook and I'd be really curious to see how it performs versus everything else. I wasted time (and money) on the other approaches and therefore I'm reluctant to invest the time in anything else.

Tiered Pricing

With the intent of producing more content, I wanted to reward people who were willing to pay up front for content that might be weeks or months in the making. I created the site membership and tried to make it as enticing as possible. For those that weren't as patient, I offered up just the e-books and the Kindle version as options.

Success?

First of all, I set my sights low. I expected most people would buy just the e-book with a few people going for the site membership. I expected to sell maybe 50 e-books within the first couple months. As of this writing, which is 2 1/2 months from when I launched the e-book, I've sold 569 site memberships and 106 e-books (and then close to 200 Kindle copies on Amazon). (A small caveat that many of the site memberships sold during the one-day sale I held on Christmas Day. That response also blew me away. I figured y'all would be eating dinner or opening presents!)

Clearly I set my expectations too low.

Should you self-publish?

I have made more from self-publishing than I have from writing for traditional publishers. I took more risks, paying for an illustrator, font rights, designing all the collateral material, paying for advertising, building the payment gateway, and investing my time in writing the book itself. Having learned as much as I have in the process has been a huge reward in itself. Having the book do as well as it has has been a fantastic bonus.

I recognize that I've built up an audience over the years and that I've been able to take advantage of that audience to get the word out. I believe that self-publishing offers up the greatest of flexibility and the greatest of rewards. I've seen lesser known individuals launch their own self-published efforts and have done similarly well.

It's cliché but if I can do it, so can you!

Naming Convention in CSS

jonathan@snook.ca (Jonathan Snook) — Tue, 24 Jan 2012 09:09:08 PST

My mind is on CSS quite a bit these days. At Shopify, I'm jumping into projects that already well under way. As a result, it's been a great way to look at what I wrote in SMACSS and see how applicable it is to yet another project. (As if Yahoo! wasn't already enough of a testing ground.)

With Yahoo!, I (and a team of people) were writing the CSS from scratch and creating our mental map of the project as we went along. Jumping into the middle of a project as I am at Shopify, I have to try and figure out why things are done the way they are.

Here's an example of something that I ran into in the CSS:

#loading-header .loading { background: url(spinner.gif) no-repeat 0 0; }
[...separated by a few pages of code...]
#content {
[...separated by more code...]
  #loading-header { display:none; }
  .row { display:block; }
  &.loading {
    #loading-header { display:block; }
    .row { display:none; }
  }
}

The loading class has a spinner. Got it. But wait, there's a loading class inside an element with an ID of loading-header and another loading class that gets added to the element with an ID of content. Are they the same somehow? Is there some inheritence that is taking place?

As it turns out, no. These two loading classes were named exactly the same thing but applied in two different contexts. They really had no relation at all except that the #loading-header (and thus, #loading-header .loading) is only visible with #content.loading. (The &.loading is part of SASS and adds #content in place of the ampersand.)

One class is a state. Because it's a state, I prefer to prepend all my states with "is-". In this case, it would be "is-loading". The question asked when I first mentioned this is, "isn't the 'is-' redundant?" But as you can see from the example, it isn't. The naming convention clarifies its intent.

In this case, I had to determine intent based on the CSS. Other times, you're looking at the HTML first.

<div id="content" class="loading">
<div id="loading-header">
    <div class="loading">

Where do you begin to look in the CSS to find what you're looking for? You'd probably start with a search for ".loading". Now you're left trying to figure out which loading class applies to what element. The swaths of CSS that separated the relevant parts made it harder to see what was going on.

The simple answer to this, of course, is not to naming two different things with the same name. However, I believe a solid naming convention clarifies intent and makes the project easier to understand. We've long applied naming conventions to programmery things like JavaScript and PHP. The same should go for CSS.

Handling CSS Transitions with prepareTransition

jonathan@snook.ca (Jonathan Snook) — Thu, 12 Jan 2012 14:22:54 PST

Using CSS transitions can be quite fun. But what's not fun is when you want to transition something that needs to use display:none or visibility:hidden (or really, any non-transitionable property).

For example, let's say you have a dialog. When the user clicks on the close button, you want the dialog to fade out — a simple transition from opacity:1 to opacity:0. The problem is that the element is still there, even though you can't see it. There's the transitionEnd event that you can use in JavaScript to set display:none at that time but that doesn't help you for browsers that don't support transitions.

I put together a small little jQuery plug-in called prepareTransition to help out and is available on Github. Feedback is most welcome.

Example Usage

Let's say you had a dialog that you wanted to hide when someone clicks the close button.

.dialog {
    position: absolute;
    /* and other dialoggy styles */
}

.is-hidden {
    display: none;
}

// and our jQuery:
$(".btn-close").click(function(){
    $(".dialog").addClass('is-hidden');
})

Now let's layer on some CSS transitions.

.dialog {
    position: absolute;
    /* and other dialoggy styles */
    opacity: 1;
    transition: opacity 1s; /* don't forget vendor prefixed */ 
}

.is-hidden {
    display: none;
    opacity: 0;
}

// and our jQuery:
$(".btn-close").click(function(){
    $(".dialog").addClass('is-hidden');
})

In browsers that don't support transitions, this will still work but for browsers that do support transitions, this doesn't work. Why is that? The display property ends up removing the element from flow before the animation even starts. Clearly less than ideal.

As mentioned at the beginning of this article, I could remove display: none from is-hidden and then use the transitionEnd event to add it back in but then I don't have something that works in browsers that don't support transitions.

The prepareTransition method forces display: block; until the end of the transition. It does this by applying an is-transitioning class to the element and then using the transitionEnd JavaScript event to remove the class from the element.

.dialog {
    position: absolute;
    /* and other dialoggy styles */
    opacity: 1;
    transition: opacity 1s; 
}

.is-hidden {
    display: none;
    opacity: 0;
}

.is-transitioning {
    display: block !important;
    visibility: visible !important;
}

// and our jQuery:
$(".btn-close").click(function(){
    $(".dialog").prepareTransition().addClass('is-hidden');
})

Using prepareTransition is a handy way of allowing an easy fallback design for browsers that don't support transitions while making it easier to manage transitions for browsers that do support it.

Added to the specification

This would be much easier if there was a transitionStart event, though. Then, a method wouldn't have to be run before applying the is-transitioning class.

Even better would be a pseudo-class that could be applied to an element.

:transition {
    display: block !important;
}

Or maybe it's just assumed that any element in transition should be display: block (and visibility: visible). In any case, we clearly need a little more at the browser implementation level to simplify this use case.

Reflective

jonathan@snook.ca (Jonathan Snook) — Wed, 28 Dec 2011 16:44:21 PST

It is once again that time of year where I reflect on the year that has passed and contemplate the year the come.

Professionally

On a professional level, this has been a fantastic year but still not without its ups and downs. This year capped my second and final year with Yahoo!. Yahoo! has been a great experience for me and exposed me to an environment that I hadn't worked in before. I was able to work with large teams on a large scale across multiple products. To know that I had a big part to play in the success of those projects is very rewarding. It gave me the opportunity to work with talented people who are passionate about what they do and I was happy to have been given the opportunity to share what I learned both inside and outside the company.

It provided me a deeper foray into accessibility, getting to speak at CSUN and at the Ottawa Accessibility Unconference on the work we did with keyboard access on Yahoo! Mail.

SMACSS

My time at Yahoo! also led me to write Scalable and Modular Architecture for CSS (SMACSS), for which the outpouring of support from the community has blown me away. As a result of that success, I'm taking a big gamble in the new year: I'll be speaking only on SMACSS and CSS architecture in 2012. This is a departure from previous years where almost every talk I did was something new.

SMACSS has also been extremely fun to work on as it has thrown me into new things that I've never done before. I've had to learn about how to create e-books, had to learn about how to market the book and the workshops, and also thrown into a world of event planning. The last couple months have been quite rejuvenating!

Writing

I still haven't picked up the pace much around Snook.ca but I'm chalking it up to being extremely busy with everything else, especially all the writing for SMACSS. I did get the chance to write for 24ways again, which has become a bit of a tradition. And I got to write about another thing I learned from Yahoo!: bidi.

Something new

So now that my time at Yahoo! is done for, what will I be doing next? Yes, I have the book, and the workshops, and other speaking gigs, but I'll still be holding down a full-time job amidst it all. As of January 3rd, I'll be working for a local company doing great things: Shopify.

I'm quite excited to starting work at Shopify in the new year. I've had a chance to meet a bunch of the folks from there and they're all quite eager and passionate. My JavaScript skills weren't put to the test very often in the last two years, so I'm looking forward to exploring CoffeeScript and Batman.js.

It does mean my return to an office environment. Gone are the days of working in my underwear. Life is rough.

Personally

On a personal level, things have slowly stabilized. My divorce was finalized after two and a half years. It was looking like it was going to drag out for years and involve courts and all that icky stuff. Thankfully, that didn't materialize, for the most part.

Having things stabilize in my personal life has, I believe, given me a greater ability to focus on my professional life again.

Working for a company in the San Francisco Bay area was both wonderful and difficult. I had tried to maintain the balance between travelling for public speaking, travelling to the main Yahoo! campus in Sunnyvale, and spending time at home with my kids. The draw to move to the Bay area was strong at times but would've meant sacrificing my time with my kids. I have not succumbed to that temptation as of yet and instead, will be spending much more time in Ottawa now that I'm working for Shopify.

I will miss the friends I made in the Bay area and look forward to seeing them again at some point in the new year.

Go, go, go!

When 2012 comes, I'll be hitting the ground running as I finalize the remaining workshop venues for SMACSS and I'll be immersing myself in the world of Shopify as I try to get a handle on everything, all the while learning new names and new faces.

2011 definitely ended on a high note and I'm excited to what 2012 has in store.