Books Writing

Writing from the bleeding edge

One of the challenges writing a book on technology is not only do you need to put words together in some form of coherent, possibly even interesting, manner, but you also have to understand the underlying technology enough to be able to explain it to others.

You can’t just “talk” about the technology, you have to understand it.

Not a problem, except when you’re getting into bleeding edge technology, like some of the ECMAScript 6 objects I’m covering in the second edition of my JavaScript Cookbook.

All you can do is work with the object, work with the object, and work with the object until you go from, “I hate this object. I hate this object. I really f**king hate this object” to, “Oh hey, this object isn’t so bad.”

Then you can write about it in the book.

Books JavaScript

JavaScript, not a ‘real language’

Simon St. Laurent and I have been discussing that exciting upcoming conference, DHTMLConf.

Party like golden sparkles following the mouse cursor is cool again!

If you’re going to JSFest, how can you not go to DHTMLConf? This is a conference celebrating a time when all of the technologies we take so seriously now, were fun!

Simon is going, and is taking along a copy of his old Dynamic HTML book he managed to find. That made me dig around online for anything on my old books, including my Dynamic HTML book (1998), as well as my earlier (1996) JavaScript How-To.

I had to laugh when I saw the marketing blurb attached to the JavaScript How-To book at Amazon:

JavaScript is the ultimate in web eye-candy. It is not a real programming language such as Java, and it isn’t really essential for web site development, but it sure is a lot of fun for tinkerers.

Books Critters

Sharing photos

Ringling Brothers: The Greatest Show in Court book coverThe photo for my newest book comes from Shutterstock. It’s not a perfect photo. It’s a little dark, a little blurry and out of focus. But no other image worked for the book. When I saw it, I knew this was the image I wanted for my cover. Authors get funny that way, which is why publishers rarely let us anywhere near the cover.

Thankfully, O’Reilly’s Director of Brand Management and expert on all things book covers, Edie Freedman, kindly volunteered to help me pummel the photo into shape. She also helped educate me on what makes a good book cover. For instance, I didn’t know about needing to leave space on all sides of the cover page. I also wasn’t aware that when you’re a relatively unknown author, as I am, you want to put your name at the top of the page; get a little name recognition going. She helped polish away many of the photo’s distractions, and find a font that, I think, really makes the cover snap—especially in smaller sizes, which is what shows up on Amazon pages.

The cover image is probably the only photo I’ll be using from Shutterstock in my book. Most of the images will come from the court case and investigations the book covers. The others are coming from photos at Flickr made freely available for use with a Creative Commons license. You can use a photo in a book, as illustration, if the CC license permits noncommercial use.

Some of the photos are from folks who have attended the Ringling Brothers circus or the associated animal walks. Others, though, come from the Circus collection of the Boston Public Library. This wonderful institution has not only uploaded extraordinary graphics and photos to its Flickr account, it kindly allows people like me to use the photos in a non-commercial setting (such as within a book for editorial or illustrative purposes). My favorite set of theirs is, of course, the one related to the circus.

I’ve always been reluctant about the Creative Commons license, not the least of which, the licenses are a bit confusing. For instance, it took me the longest time to figure out that using a photo as illustration within a book that isn’t focused on selling said photo is not a commercial use of the photo. Or at least, that’s the interpretation I’ve seen most frequently given, and the one I’m sticking with.

I can now see, though, why having a licensing scheme such as the Creative Commons is so helpful. It wasn’t necessary to have older photos and circus posters in the book…but the added color and history makes it more lively.

Old circus poster

I was so grateful to the Boston Public Library that I decided to upload all of my photos to my new Flickr account and offer them for use. The CC license I picked is very open, other than I restrict commercial use because I don’t have model releases for people and buildings and don’t want to hassle with the potential content copyright issues.

I’ve already had one of my photos used in a Missouri Department of Tourism pamphlet, for illustrative purposes. I don’t claim to be the best photographer in the world, and most of my photos are ordinary. But you never know when one of your photos might help someone, so I just uploaded them all, let folks use them or not.


New books, new writing experiences

I have been working on two books the last several months. Well, one is more of an interesting writing project than a book.

O’Reilly has created an online writing tool and online book reader, named Atlas and Chimera, respectively. The online writing tool, Atlas, currently uses AsciiDoc to annotate the text, though I believe it is undergoing user interface changes in the future.

I excerpted out several sections from the first edition of the JavaScript Cookbook, updated them, and then added live examples via the use of JS Bin (access the book online). Adding the live bits actually impacted on the writing. There was something about embedding live code that connected me to the reader, and my writing style became more relaxed—more comfortable. Additionally, it connected the code samples and the writing more closely. I found myself drilling just a bit more into the code than I had done before, in order to understand more fully exactly why the code worked the way it did. Having a working example of the code right in the writing, altered both.

When I write the second edition for the JavaScript Cookbook, I’ll be using Atlas. I genuinely believe it helps me be a better tech writer. And who doesn’t like live embedded examples?

The use of Atlas also gives writers so much more control over the book. When Node finally hits 1.0, I’ll be using Atlas to update my Learning Node book to incorporate errata, as well as changes that have occurred because of the formalized Node release. It’s a fix of the existing edition of the book, rather than putting out a new edition. Owners of digital copies of Learning Node will be able to access an upgrade for free. Now, this is the way tech books should be written and published. Sometimes you don’t need a whole new edition, you just need to tweak the existing book.

We authors can also see what the book will look like when it’s finished, as we write it. We can publish to Chimera, or to .mobi, ePub, and PDF. Now I can see for myself when lines of code are too long, or if I’ve crowded too much code into too small a space. I like this. I like this a lot.

Publishers just don’t seem to understand that writers really do want more say in the production of our books. We want more control over the process. Times are changing, and the days when an author gave up control over the book as soon as it began the print process, are over.

My hope is that O’Reilly will jump into the self-publication world by expanding Atlas for non-O’Reilly press books. It needs to provide a way to customize the CSS, or at a minimum, pick book layout themes. It also needs to provide a way for self-publishers to charge for publications—with O’Reilly taking a cut like other self-publication venues do. Lastly, it needs a way to import and export ePub content from tools such as Sigil. This last one is important, as it allows a person to go from online to offline and back again.

O’Reilly knows freelance graphic artists, tech and copy editors, and book production people. It has the facilities to connect self-publishers with the professionals who can, for a fee, help polish a work. And O’Reilly could do well, I think, by charging the same for self-published books that Amazon and others charge, and with a minimum of risk.

It would need to ensure that people know that these books are not O’Reilly books, and haven’t gone through the O’Reilly production process. That’s the only risk I see if O’Reilly expanded into this new and extremely vibrant branch of the publishing industry. However, Atlas has facilities for a person to start their own press. I haven’t tried this piece out, but it does seem to fit into my Atlas/Chimera wishlist.

I see all the scaffolding in place, so I’m hoping O’Reilly dips the corporate toe into the do-it-yourself publishing waters. No sharks, only minnows with nubby teeth.

Speaking of self-publication, the second book I’m working on is my first self-published work. Some of you know about it; many of you do not. I don’t have my Small Books web site up and running yet for the formal book page, so I’m just going to tell you about it, sans marketing.

The book is named “Ringling Brothers: The Greatest Show in Court”. It came about when I read a news story a couple of years back about Feld Entertainment, owner of the Ringling Brothers and Barnum & Bailey Circus, suing various animal welfare groups under the Racketeer Influenced and Corrupt Organizations Act—otherwise known as RICO.

There are some news stories that stop you in your tracks, and a circus suing organizations like the ASPCA and HSUS for racketeering was one such story for me. What on earth could happen that would culminate in a lawsuit accusing animal welfare groups of racketeering? I mean, we don’t automatically group the ASPCA in the same category as, say, Whitey Bulger and the Gambino Crime Family.

“You better take care of them cows or you’ll sleep with the fishes”, doesn’t exactly sound like a line from a detective novel or Al Pacino movie.

So, I started digging. I found that the RICO case was based on another 10+ year court case where several animal welfare groups sued Ringling Brothers under the Endangered Species Act for the circus’s treatment of elephants.

Hmm. “You better take care of them elephants or you’ll sleep with the fishes”, still doesn’t sound like a line from a mob movie.

What I found about both cases, the state of the law protecting elephants in this country, the unfortunate malleability of RICO, and Feld’s other rather colorful court experiences fascinated me enough that I kept digging. Digging, which led to me downloading thousands of pages of court documents, transcripts, and exhibits. After supplying the DC district court with at least five new computers and a printer in PACER fees, I decided to turn these interesting, but complicated, court cases into a book. Just for good measure, I’m also throwing in a little history about elephants in circuses in the US.

Definitely not a book on JavaScript. Not even a book about JavaScript, sleeping with the fishes.

I am both terrified and incredibly excited about “Ringling Brothers: The Greatest Show in Court”. If I can control my dithering and fussing, it should be on digital bookshelves this fall. When I can pummel my Small Books site into shape, I’ll post a link to a more formal introduction to the book.

Books JavaScript Technology

Finished tech review and the move to Node 0.8x

Just finished the final tech review of my Learning Node book. At 400 pages, it’s a big book. I must admit to being more than a little tired. Right now, I feel I could sleep for a week.

The big announcement in Node land is that unstable 0.7.x is being moved to stable 0.8.x next week. As a final act for my book, I put all the examples through a 0.7.10 tests. The results were better than I expected, not as good as I hoped.

I hit a couple of minor deprecation issues. For instance, path.exists has been deprecated in favor of fs.exists. I used the exit event with one child process application, and I needed to convert it to the new close event. This new event not only waits for the process to end, but all stdio pipes are closed.

Other modules ran into the same deprecation issues. Most of the testing modules in Chapter 14 won’t work with Node 0.8.x, but I think the changes to make them work will be minor.

Socket.IO didn’t work with 0.7.10 and the developers know it. I’m more than a little surprised at the reaction to people turning in issues related to the problem. Not to mention, closing the bugs without even attempting a fix. As I wrote in comments to the issues, today’s 0.7.x stable is about to become next week’s 0.8.x stable, and this bug is going to get very popular.

The db-mysql module also didn’t work with 0.7.10, and the highly popular jsdom module also had problems.

I noted the compatibility issues in the chapters, and provided alternative examples for those I could correct. That is the best I can do.

I’ve giv’n her all she’s got, Captain!