Martini Lab A blog by Chris Williams

The Command Line Book

January 17th 2017 by

Instagram pics of the book in progress.

I wrote a book! Last November, I put the final touches on a two-year process and hit the big “Publish” button. The idea behind the book started as an observation made by Paul Irish. It was some talk he was giving about… web development probably, and while he was showing some Terminal use he made an aside about how every developer should get comfortable with the command line. That was a seed I held onto and began to observe the difference between those who regularly use the command line and those who do not.

Here is my somewhat obligatory post on how I got started (and finished) writing The Command Line for Web Developers. Going into it, I had a much different expectation on what should be the way to write a book or at least how I was going to write it. By the end, I wasn’t too far off, much of the way I wrote it was how I had planned. Some things worked well, and others needed some adjustment.

On December 23, 2014, after several emails, conference calls, and market research surveys, I got my acceptance email for the then-titled book The Command Line for Web Developers and Designers by Manning Publishing. I got an ISBN and everything.

And then I dumped them. Okay not true, but I did end up severing that relationship with them after a point. For the most part, Manning Publications was great to work with. They have a very prescriptive writing model that they expect all of their writers to follow. This includes writing out plans for every chapter, outlines within outlines, what kinds of code examples will be shown, etc. I found the planning aspects of process incredibly helpful.

The Manning Way

The communication and revisions between me and the assigned editor were not very helpful after a point. This isn’t a dig. What ended up as a guided mission on writing a book turned into a two very different takes on how that should ultimately play out. Little things would come into the process that slowed down my writing and just added to the time it took to write.

For example, I write everything in the book using Markdown. It works well with my code editor which I am already comfortable using. It is just text, so it works perfectly with Git. I can pull it up in preview on GitHub from multiple devices. Or by using Pandoc, I can send it to PDF to read offline.

However, my editor rejected the first chapter because it was plain text. They expected Microsoft Word. And it had to be in the Manning approved format. That meant the paragraphs needed to be at a specific point size and a specific font. Chapter titles had their own format; images had to be followed with descriptive text and numbered. The Word file the gave me had every kind of formatting rule for Manning to work with and it was on me to handle that. Pandoc can convert to Word files as well, and it can keep formatting options of Word docs provided the format styles are named a certain way.

$ pandoc -s -S 2-4-setting-up.md --no-highlight --reference-docx manning2.docx -o ch04_williams_TheCommandLine.docx

The first chapter took a long time to write as well. Manning typically offers the first chapter to readers as a free sample to help make their purchasing decisions. The first chapter truly had to be a preview/summary of the entire book.

I really struggled with this. I had a hard time trying to cover every subject in the book into one chapter. I could go back into my Git history and look, but I ended up with multiple–completely different–versions of the first chapter in an attempt to satisfy my editor's requirements. At some point, we agreed to move on and revisit the first chapter later.

This was about the time when I began to understand that my editor didn’t understand what I was writing about. The Terminal, the command line, Bash, Yeoman, Gulp, npm, all of these are related and yet I couldn’t satisfy the constant question that came up during our review: so how is this related to the command line? It was a frequent conversation that discouraged me in that I felt I wasn’t properly writing to educate my editor (and my readers) the whole point of the book!

A discouraged writer writes slower. Chapters took longer to complete. Deadlines were extended. Meetings were postponed. It wasn’t until our last conversation about style changes to Manning books that I realized it wasn’t me. Manning had just changed how their books format chapter summaries. Chapter summaries were now required to have a descriptive paragraph and an itemized list of topics covered in the chapter (or maybe it got rid of the list and make them into paragraphs). This was another example of their specific roadmap for specific subjects. However, I wasn’t writing about Gradle, or Java, or RWD, or one single technology. My book (my vision of the book) didn’t fit perfectly with the expectations of their format.

So I canceled our arrangement and returned to writing it the way it best fit me.

Writing on my own

Truth be told, Manning’s approach to planning and executing was very reliable. Have an outline of the entire book with its subsections. Write at least a few paragraphs for each subsection to be appropriately sized. Plan out each chapter so you know what new concepts you will explain, what examples you can provide, what kind of illustrations or diagrams go with it.

I also switch gears in the tone of my writing. I found that having a casual, less formal, tone in my writing made it easier for me to get points across that were traditionally very academic. I also didn’t have to explain the technology that the reader should already be familiar with. Since the book’s audience is intended for web developers, I didn’t have to explain technical concepts of using a bootstrap CSS framework for example.

I did, however, cough up money for a freelance editor to go through checking my writing for grammar, writing styles, and call out any points she felt might use more detail. By the way, if you’re ever in a position to hire an editor, hire Molly Gunn.

Self Publishing

There are many options for publishing your own book. The search results on that are wide and varied. Depending on what you are looking for, publishing companies offer print-on-demand services, print bundles, channels to Amazon, ISBN registration, etc. I was already familiar with LeanPub having bought books there on programming, so I knew about their marketplace and concluded them to be the best fit. They have a good payout model for authors. Customers can adjust the price they’re willing to pay as well. Authors can publish new updates to books and readers get an email notification to get the latest edition. They also happen to use a sophisticated tool for importing Markdown docs and converting them into downloadable formats for reading devices. Sign. Me. Up.

The shortcomings of LeanPub are small but worth considering. For one, styling a book is limited to what is built into LeanPubs tools which isn’t much. You can set the page dimensions and have a couple of fonts to choose from, but that is it. LeanPub can interpret code examples, include line numbering and syntax highlighting, but it wasn’t consistent for me, so I left that feature off.

You can, however, continue to develop and publish your book throughout the writing process. Dr. Axel Rauschmayer’s Exploring ES6 is an example of a book that is still growing and updating itself as the ECMAScript evolves. Once a book is finally complete, there is a little-known option for the author to provide a finalized PDF (not auto-generated). Since I was also printing the book and had to move everything into InDesign, as well the need for an index, I went that route.

Amazon’s on-demand publishing service, CreateSpace, requires a PDF that adheres to a stanard set of page sizes and margins. The process is very involved, but it covers pretty much everything in getting your book onto the Amazon marketplace.

InDesign, Out Sanity

I’ve worked with Adobe products since the beginning of my computer experience. The difference between products is staggering, and InDesign is no exception. The difference between its origins as Aldus Pagemaker and what it is now might as well not be measured.

Knowing what I know now, I would have hired someone to tackle this part of the process. Picas vex me.

InDesign doesn’t import Markdown files. I found a couple of “scripts” that attempted to solve the issue, but I had too much difficulty getting them to work. It probably took someone with more InDesign experience to pull it off. Pandoc can convert to IDML, a format for managing external text in InDesign. That was the best option.

$ pandoc -s -f markdown+multiline_tables -t icml -o 3-8-text-editors.icml 3-8-text-editors.md

The only issue with this approach is InDesign will break on import when it reaches an image reference in the IDML file. So before I ran this command, I took out all the images and their descriptions so I could add them back in manually.

That ended up being the biggest challenge. With webpages, text and images just flow together. But a page has a limited dimension and the image or illustration your text may be referencing might not fit on the same page. So you have decided if the image sits on the next page or it might need to resize. What you end up with is text that says “In the illustration above” and it's not there! Luckily, and smartly, InDesign can reference other portions of a document through hyperlinking. Images and hyperlinking could be a blog post on its own.

Step 3: Profit!*

Putting it all together and finally hitting the proverbial “Publish” button was a major milestone. Now I just have to market it, sell it, register the copyright on it (that’s a whole other process), learn about Amazon SEO which is a thing, solicit reviews, create coupon offers, all the things.

Since the book has come out, the technology I wrote about has changed, and the text could use those updates. I already changed references from Grunt to Gulp. Bower is all but abandoned in the front-end ecosystem. Apple put out yet another OS update, and Windows users are finally getting a native Bash option.

The plan now is to get the book onto the web. There goes the profit part of this! Monies Leanpub and Amazon will help pay for the work in getting the book online for everyone, as well as all the updates.

Update: /the-command-line is now in development.