Category: Writing

Just writing

Categories
Books

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.

Categories
Writing

Write! Write!

Laura Dern in Jurassic Park

There’s a scene in Jurassic Park where the character played by Laura Dern, having just escaped being raptor kibble, sees her close friend (played by Sam Neill) in the distance. She softly shouts out through gritted teeth, “Run! Run!” She’s not telling Neill to run; she’s telling herself to run.

She’s not telling Neill to run; she’s telling herself to run.

Critics have panned the scene, accusing Dern of overacting. I thought it was a good scene, and the acting was appropriate to the context.

Here is a person who has just barely escaped from a large, intelligent, and scary reptile who had recently munched down a park employee, leaving only the grisly remains of his arm. When she sees her friend, who represents both familiarity and safety, she wants nothing more than to run to him. She wants to run so badly, she’s actually incapable of running. She has to tell herself to “Run!” to break through the paralysis before she can manage to limp to Neill. In the scene, she demonstrates what can happen when we’re overcome with such a strong desire to do something, we’re incapable of doing anything.

I look at my dormant websites and I think of all the things I want to write. There are so many things I want to write about, and I want to write about them so badly that I find myself frozen, just like Laura Dern … but without ravening beasts at my back.

The Trump Presidency, his cabinet, the environment, technology, climate, animals and their welfare, people, life…there is so much going on nowadays, so many topics that interest me, so much I want to say that I find myself not being able to say a damn thing. Instead, I fuss, and I plan, and I research, and tweet/Facebook and then I fuss some more. I’ve fussed over my site for weeks without writing one single word to it.

So here I am, Laura Dern-like, crouched at my laptop with hordes of ideas breathing down my neck, telling myself to “Write! Write!”

If for a time I limp instead of leap, at least it’s better than silence.

Categories
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!

Categories
Books Writing

Changing course

Learning Node will be my last book for O’Reilly, at least for the foreseeable future.

Learning Node was a particularly exhausting book. Not only is there much to cover in one book, Node is a very dynamic technology. I like to think my coverage is both comprehensive and solid, but I guess we’ll see how the book does when it hits the streets.

In the next year, I’m going to enter the ranks of the self-published. I’m also focusing less on technology, and more on other areas of interest. What these areas are will become evident over the next several months.

My next book won’t be on technology, and I’m not sure that the one after will be on technology, either. I’m not saying Learning Node is my last book on technology, but I am most definitely taking a break from the tech book field. Most tech writers will understand when I write about the challenges in providing decent and accurate code examples for a new or changing technology, at the same time you’re trying to ensure that your grammar is correct, and your prose is clear and readable. Not only do you have to worry about your comma use in your text, you also have to worry about comma use in your code.

Just when you finally punch all the code, screen grabs, and text into a comprehensive whole, you’re then faced with an audience that’s just as likely to tell you it’s not interested in buying a book when they can find the material online, and for free.

I’m one of the lucky tech writers in that all but a couple of my books have earned out the advances, and provided relatively decent royalties. I’m not a bestselling author, but to earn out advances on 20 books isn’t bad in the tech field. At the same time, though, I’m not making it as a writer, and I have to try something new. That, or see if the local McDonald’s is hiring, because my days of tech contracting are over.

I plan on being as innovative as possible with my self-published works. For one, I don’t see any of the books being very large. Electronic publishing opens the doors for focused, shorter works, attractively priced. By attractively priced I mean that I don’t see any of my books priced at more than $5.00. In fact, I envision a Starbucks pricing model, with book prices comparable to prices you’d pay for a Starbucks coffee: smaller books will be equivalent to the price for a tall latte; larger, more complex works, closer to the price for a venti Caramel Macciato.

Lower prices and shorter works does not mean the books won’t be solid. My first self-published book is on a topic I’ve been researching for three years. But it’s a focused topic: too big for a Kindle Singles, and way too small for a more traditional book. It’s a topic that greatly interests me, and I think that’s the most important consideration.

Of course, I still have to worry about grammar and the damn commas, but at least I don’t have to worry about code.

Categories
Technology Writing

Node: References and Resources

Recovered from the Wayback Machine.

During my explorations of Node.js, I came across many excellent resources, references, tutorials, and various other online publications related to the technology. I had planned on incorporating this material into an appendix for Learning Node but decided it would make a better online resource than a book chapter.

Every person interested in Node should start with the Node.js web site, as well as the web site for npm, the application that manages Node module installations:

If you’re interested in Node in a Windows environment, you might a little extra help in getting set up. I recommend the following resources:

There’s an enormous number of resources for the Node.js newbie, including basic tutorials and entire online books. I know there are more than what I discovered, but the following is a good start:

One person, Felix Geisendörfer, has provided several excellent online resources for new and experienced Node folks:

As you learn Node, you’ll hear about the Node event loop. The following are a couple of good articles on the event loop:

REPL is the Node interactive stand alone application. REPL stands for Read-Eval-Print-Loop. Following are good REPL resources:

Modules are the heart and soul of Node.js. It can be an interesting experience finding Modules, because you need to look carefully among the many available to see which are the ones currently supported, and which have, more or less, been abandoned. Luckily, there are good Node module resources:

A good rule of thumb about which module to use is check for recent activity in the module’s repository. Are there outstanding issues? Pull requests that have gone unanswered for a long time? Also do a Google search, see who is using the module, for what, and how recently.

For more on npm, itself, do check out the Developer guide. Also spend some time understanding the differences between global and local installation of modules.

Node is based on the CommonJS model. If you want to learn more about CommonJS, I recommend Taking baby steps with Node.js–CommonJS and creating custom modules.

The heart of the module system is the package.json file. Nodejitsu provides an article and a couple of good cheat sheets related to package.json and npm:

Peter Krumin did a great series of articles on Node.js Modules you should know about. Several of my favorite are included in the list.

If you work with Node, and you write modules, chances are you’re going to become intimately involved with EventEmitter. The following are good EventEmitter resources and references:

Control flow is a big topic of interest for Node developers:

There are good frameworks for Node, but I focused on Connect/Express. I felt that Express was more Node-like, and requires less upfront time than the other frameworks. That’s not to say there weren’t challenges with Express, as it went from Express 2.x to Express 3.x and then back down to Express 2.x, but one adapts. I focused on Express 3 in the book.

Connect is the middleware layer for Express. TJ Holowaychuk provides an introduction to Connect 2 at Connect 2.0. The Express web site is at Express.com, though note that the documentation is still focused on Express 2. For the Express 2 developer, check out the Migrating from 2.x to 3.x guide. Mike Valstar writes specifically about Express error handling and 404 pages.

I grew fond of Redis when working with Node.js. The Redis site is at redis.io. Redis is nicely documented, at the site and in the Little Redis Book.

Following are other articles and links of interest, in no particular order or grouping:

Hack Sparrow article on running Express application in a production environment http://www.hacksparrow.com/running-express-js-in-production-mode.html. Charlie Robbins provides a how-to on distributing Node.js apps with Hook.io at http://blog.nodejitsu.com/distribute-nodejs-apps-with-hookio. More on the Hook.io module at http://ejeklint.github.com/2011/09/23/hook.io-for-dummies-part-1-overview/.

Rasmus Andersson wrote a Template for setting up Node.js-backed web apps on EC2 at http://rsms.me/2011/03/23/ec2-wep-app-template.html. Another writing on setting up Node on Amazon EC2 from Ben Nadel at http://www.bennadel.com/blog/2321-How-I-Got-Node-js-Running-On-A-Linux-M….

A XSS (Cross Site Scripting) Cheat Sheet can be found at http://ha.ckers.org/xss.html. Another cheat sheet, this time on SQL Injection at http://ferruh.mavituna.com/sql-injection-cheatsheet-oku/.

Heroku provides instructions on how to create a self-signed SSL certificate at https://devcenter.heroku.com/articles/ssl-certificate-self. Another tutorial on the same subjec. at http://www.akadia.com/services/ssh_test_certificate.html.

I don’t cover backbone.js in the book, but an article on combing it with MongoDB, Mongoose, and Restify can be read at http://backbonetutorials.com/nodejs-restify-mongodb-mongoose/.

A comparison of Redis and Cassandra http://hammerprinciple.com/databases/items/redis/cassandra. More on Apache Cassandra at http://cassandra.apache.org/. Redis is compared with Memcached at http://webdevrefinery.com/forums/topic/8221-memcached-vs-redis/. The Memcached web site is at http://memcached.org/.

Guillermo Rauch’s Use Jade Blocks, not Layouts, at http://www.devthought.com/code/use-jade-blocks-not-layouts/.

Curl is your friend when testing RESTful applications. Some helpful examples at http://www.yilmazhuseyin.com/blog/dev/curl-tutorial-examples-usage/.
The Ruby on Rails routing guide applies equally well to Node: http://guides.rubyonrails.org/routing.html.

Charlie McConnell wrote an article on “How to use stream.pipe” at http://docs.nodejitsu.com/articles/advanced/streams/how-to-use-stream-pipe.

One of the better, more thorough answers I’ve seen at Stack Overflow is the answer to “What is the Difference between proxy server and reverse proxy server” at http://stackoverflow.com/questions/224664/difference-between-proxy-serve….

Guillermo Rauch wrote a multipart tweet filtering proxy, beginning with Part 1 at http://www.devthought.com/2012/01/24/filtering-tweets-for-your-favorite-….

Shravya Garlapati at LinkedIn, wrote a very helpful article, Blazing Fast node.js: 10 performance tips from LinkedIn Mobile http://engineering.linkedin.com/nodejs/blazing-fast-nodejs-10-performanc….

The Async module can be found at https://github.com/caolan/async. More on the creation of Async at http://caolanmcmahon.com/posts/asynchronous_code_in_node_js.

The Step module is located at https://github.com/creationix/step.
There is promise support in Node with Q at https://github.com/kriskowal/q, and deferred https://github.com/medikoo/deferred, as well as Futures https://github.com/coolaj86/futures.

Yes, you can use Node modules with client-side JavaScript with help from RequireJS at http://requirejs.org/. And you can scrape web pages using Node, jQuery, and Jsdom, with a little help from this article http://liamkaufman.com/blog/2012/03/08/scraping-web-pages-with-jquery-no….

Since Node is based on the CommonJS model, read more about CommonJS at http://www.commonjs.org/. An interesting article on Node, CommonJS, and custom modules by Jan Van Ryswyck can be found at http://elegantcode.com/2011/02/04/taking-baby-steps-with-node-js-commonj….

A Nodejitsu article on using the Process module can be found at http://docs.nodejitsu.com/articles/getting-started/the-process-module. More on Node and processes by at http://dailyjs.com/2012/03/22/unix-node-processes/.

More on TCP Socket Programming in Node.js at http://www.hacksparrow.com/tcp-socket-programming-in-node-js.html. A general article on TCP vs. UDP can be found at http://www.skullbox.net/tcpudp.php. More on UDP Networking at http://twistedmatrix.com/documents/current/core/howto/udp.html.

If you’re curious about the performance differences between using process.nextTick and setTimeout, you can view benchmark tests at https://gist.github.com/1257394.