I wrote a book about creating custom Rails generators to help other Rails developers learn to create custom generators quickly and efficiently. I’m still putting the finishing touches on some of the additional resources, but as of today, it’s available for anybody to pick up a copy.
If that sounds interesting, that’s all you need to know. If you like context and background around creating info-products, the rest of this post is for you.
Exploration & Serendipity
I’ve been using Rails since 2007, and through the years, I made a handful of attempts at creating custom Rails generators. It worked, but each time I wasn’t eager to create more. Then one day, the significance of the potential time savings was too much to ignore, and I sat down to understand their secrets.
That opened countless opportunities to create custom generators. Some of those ideas panned out, and others were dead ends. Through all of it, generators became a powerful tool that helped save time and tedium.
After being laid off about a year ago, I put together an in-depth blog post about creating custom Rails generators and thought that was enough. As I kept digging deeper and talking to other Rails developers, however, I realized it was only scratching the surface of their potential.
Around that time, Amy and Alex released LaunchFTW, and I devoured it. The knowledge wasn’t new to me, but it was presented in such an approachable and actionable way that it pulled me in. I knew I wanted to create something again, but I had no idea what to create. It sparked something, and conversations with other Rails developers started to clarify how few people were taking advantage of custom generators.
Almost on a whim, I decided to expand on that blog post and create a book that went further to explain the nuances of generators so any Rails developer could run with them. What started as a plan for about 20,000 words evolved into somewhere around 40,000 words and a handful of cheat sheets.
I thought it would take a few months tops, but the research process continually surfaced topics worth sharing. And like they say, if you ever want to find out if you understand something, try explaining it to someone else. While the book covered generators in-depth, the core of the vision revolves around saving time, and browsing back through a long-form back after reading it doesn’t save time. So Frictionless Generators also includes some quick reference and cheat sheets to help remember the names and aliases of various methods to streamline learning after reading the book.
I had written and self-published books before, but I had never written a technical book. The challenges of presenting code within prose are virtually endless. I ended up using a combination of Markdown, LaTeX, Pandoc, and a rather unique custom Rails generator to handle all of the production. If it wasn’t for the generator, the process would have been a footnote at best, but since we’re talking about generators, it’s a different story.
Generating a Book about Generators
I’ve long preferred writing prose in Markdown, so that was non-negotiable. Translating a book from a collection of Markdown files to PDF and ePub files that are pleasant to read introduces some significant challenges. While there are some good solutions out there, they all involved compromises that I didn’t love. The only way to create the book I wanted to read would be to go all of the way down into the weeds with Pandoc and LaTeX.
Initially, I was scripting some basic Pandoc commands to generate the files, but after a few days I realized I was “just” generating a bunch of different files. It was a somewhat face-palm kind of moment because I was jumping through all sorts of hoops to make a Ruby script generate text files by transforming one type of file into another. It’s not exactly the type of work generators were designed for, but the type of work fell right into generators’ wheel house.
I shifted from writing a script to creating a generator that could take a set of hybrid Markdown/LaTeX files and convert them into pure Markdown files. For the PDF, the hybrid Markdown files are converted to a series of LaTeX files that specify the content and the design/layout. Then pdflatex command could process the LaTex to create both the full version of the book and a sample version.
That was great, but I still needed an ePub. After some trial and error with Pandoc, I found that generating the ePub from Markdown rather than LaTeX got me closest to the results I wanted. Fortunately, with the generator, it was relatively straightforward to create a custom process for the ePub.
Then, as a bonus, I added logic to automatically compress and zip up all the generated files into distribution-ready packages. The generator puts the quick reference sheets and sample chapters into a downloads folder, and the final files are saved into my website’s repository so they automatically end up in version control.
The code is custom enough that there’s not much value in sharing it as is, but the tactics I used will be making their way into future posts here, and that brings us to the next steps.
What’s next?
I’m polishing up a few additional resources, but I didn’t want to hold up releasing the book. So I’ll be finishing those in the coming weeks, and they’ll be available to download to everybody that purchased the relevant package.
But this is only the start. I’ve captured countless topics and notes to write posts that go even further with generators. Some are topics that felt like they didn’t belong in the book, and some are over-the-top examples of what generators can do for us. (Often unusual enough that one could argue they’re abusing generators, but they can still help broaden our horizons.)
I’ve also been working on creating dynamic online tools to help streamline the process of creating generators and even an enhanced generator generator that can generate tests, templates, arguments, and options all from the command-line. I’m planning on releasing that as a gem as well as using it as material for posts about creating more advanced generators.
I’ve also been collecting notes on opportunities to fill in some additional information in the Rails documentation for generators, and I’ll carve out some time for that as well.
Writing and producing the book has been all-consuming, but now that that process is winding down, I’ll be sharing and exploring more about generators. I’m excited, and I’m looking forward to sharing a ton more about how we can all save time with our Rails apps.