super big tree

blog.

interests, updates, & how-tos:

sethvincent:

To boldly go where no pizza has gone before.

sethvincent:

To boldly go where no pizza has gone before.

reblogged via sethvincent

Getting a technical book to v1.0: what does it mean to be “done”? The story is told.

For almost a year I’ve worked part time on a series of books about JavaScript, and I’m now almost finished with at least one of those books.

My book Development Environments for Beginners started as a dare. I dared myself to write a book in a weekend.

I succeeded at meeting my goal of a 50-page book in a weekend, but I also realized that 50 pages wasn’t enough. Over the past few months the book has increased in size to almost 100 pages, and it’s now getting close to “done.”

But what the hell does it mean for a technical book to be done?

Or any book for that matter?

It’s relatively easy for me to imagine how to decide a fiction book is completed.

There’s a story that needs to be told, and with each revision we add, remove, and revise to more effectively tell that story. We craft the plot, the characters, and other elements all in the pursuit of telling a story.

But what if we can use a similar approach for technical books?

What if we can think of a technical book as a story?

The main character of a technical book is you, the reader. You’re on a journey through a strange world learning a language you don’t understand. The goal is to achieve a level of mastery in some area.

You’ll face a series of challenges that add to the story, that add to your understanding of the topic.

So in that context it’s easier for me to conceptualize what it takes for a technical book to be finished.

A basic pattern for a technical book might be like this:

  • The main character has a goal
  • They go on a journey in order to achieve that goal
  • They face challenges and learn more about themselves and their goal
  • They achieve their goal, or realize that their original goal may have been incorrect, and revise their plan

You may notice that this pattern almost mirrors the hero’s journey, a common pattern for myths and fiction stories.

It’s fun to imagine a new programmer learning JavaScript as Frodo battling Orcs and attempting to stay strong under the influence of the power of the ring. Except bugs in the code are Orcs and the internet is the ring. That could be taking things too far, but I’m mostly ok with that.

Wait, so is Development Environments for Beginners finished?

Maybe?

The main character of this book, the reader, has a goal of learning how to create development environments. At the beginning of their journey they acquire a rag-tag team of tools consisting of the terminal, git, GitHub, and Vagrant. On their adventure they learn about testing and building projects with Ruby, JavaScript, and Python.

By the end of the book the reader has met their goal. They’ve created a few different development environments in different languages. And over the course of their journey they’ve probably had an outcome that they didn’t expect: that they prefer one of the three languages, and want to continue on with that language in a more focused way.

So yeah, maybe Development Environments for Beginners is getting close to done, at least based on this silly hero’s journey criteria.

And the remaining revisions leading up to v1.0 will all be based on improving the story, the journey of the reader.

Want to help determine when the book is finished and help guide it’s direction?

You can buy it here at a discount: https://gum.co/dev-envs/coolbud

 

Zero to book in less than 12 hours with Leanpub & Gumroad / Printing zines to creating digital books in less than 10 years.

10 years ago I made weird zines with friends. The experience of seeing people around town reading our articles got me hooked on the act of publishing.

Since then I’ve been the technical advisor to a student newspaper, made more zines and blogs, started making games, and worked as a freelance web designer and developer, contributing to open source when I can.

In the past year I’ve experimented with “lean” publishing.

Inspired by Leanpub.com and talks by Peter Armstrong I’ve gone from thinking about working on books to actually doing it.

Recently I spent one day going from the idea for a book to releasing the first version. At the end of the day I released version 0.1.0 at about 46 pages (I try to use semantic versioning for books).

People can get the book for free or pay what they feel it is worth, and they’ll get all updates to the book for free.

What I’m really excited about is that I was able to from having the idea at around 11 a.m. to a releasable product before 11 p.m., including breaks for dinner and walking the dog.

This book was easier to get started with than others, because it is a collection of existing and new tutorials about JavaScript modules. But even so, I wrote 28 of the 46 pages and revised many of the other pages in that one day, leaving only a small amount of time for production of the cover and similar assets, as well as generating the files, setting up a “pay what you want” form, and making revisions to include it on the learnjs.io site.

I was able to get the book prepared quickly because Leanpub.com and Gumroad.com make it easy.

In about 15 minutes at the end of the day I had set up a book on Leanpub and generated pdf, epub, and mobi copies of the book. Another 15 minutes and I had the book set up on Gumroad, providing a more aesthetically pleasing purchase experience than Leanpub.

The actual hard work was spent on writing, experimenting with the code (it’s a technical book) and creating the cover image. The stuff I enjoy working on.

Knowing that it is fast to get a book set up on Leanpub and Gumroad is a strong motivator for doing the work in the first place. The idea that I can create valuable content and quickly turn around a releasable product to get feedback from readers is fun.

Back when I got started with publishing the hassle of having a publication printed was part awesome fun & part insane headache. And while I miss smelling the ink and getting to see big printers in action on a regular basis, I love the simplicity and flexibility of releasing publications digitally.

npm recipes is a new book and tutorial series on learnjs.io for showcasing awesome modules found on npm.
There are over 50,000 modules on npm, so there’s a wildly big number of opportunities for checking out how various npm modules can work together.
You can read some of the tutorials on learnjs.io, and more will be released only in the book.
Get the free book here: http://learnjs.io/npm-recipes

npm recipes is a new book and tutorial series on learnjs.io for showcasing awesome modules found on npm.

There are over 50,000 modules on npm, so there’s a wildly big number of opportunities for checking out how various npm modules can work together.

You can read some of the tutorials on learnjs.io, and more will be released only in the book.

Get the free book here: http://learnjs.io/npm-recipes