Raible Designs

The JHipster Mini-Book: How We Did It and What's Next

Last Friday, the JHipster Mini-Book was published on InfoQ. I wrote about this milestone on the book's blog. I'm pumped to see this release happen, and I'd like to give you a behind-the-scenes peak at how it went from idea to production.

The Idea
At the end of last year, I wrote down my goals for 2015:

• 21 Point Fitness App
• JHipster Mini Book (InfoQ)
• Finish Bus
• New House
• Good Blood Pressure

My reason for wanting to write a JHipster Mini-Book was simple: I knew AngularJS, Bootstrap and Spring Boot quite well. I'd used them on several projects and I really liked how JHipster married them all together. I often ran into people that used these technologies, but hadn't heard of JHipster. I was hoping to make more people aware of the project and market my development skills at the same time.

The first step to accomplishing a goal is writing it down. After writing it down and sharing with friends, I sent an email to Charles Humble, InfoQ's Head of Editorial, in early January. Charles directed me to InfoQ's internal mini-book guide and recommended I create an outline and talk to the project owners. It took me six weeks before I created an outline and sent it to Julien Dubois. We went back-and-forth on the outline for a while and finalized it around the beginning of April.

On April 8, I delivered a talk on JHipster at Denver's Java Users Group and announced I was writing the book.

The Development Process
Early on, I'd decided I wanted to write the book with AsciiDoc and build it with Asciidoctor. I did receive some slight push back (to use Google Docs) from InfoQ, but they were mostly supportive. Their biggest concern was getting it into a desktop publishing program and formatting it to fit their style. I have an email that says "this is going to be the most expensive book we’ve ever produced!".

I chose Asciidoctor because I wanted to run the book development and publishing process like an open source project. I also found its ability to import source code quite handy. I used the asciidoctor-gradle-examples project as a starting point, specifically the asciidoctor-to-all-example. I hadn't used Gradle on a project before, so I was motivated to learn it. Now that I think of it, I never even bothered to research how to use Asciidoctor with Maven.

I used JIRA in the cloud ($20/month) to create tasks, organize sprints and track my progress. I broke things down by chapter, starting with the UI components section, followed by Building an app, and API building blocks. I used the outline of the book to create my tasks. I gave myself a couple weeks for each chapter, but it ended up taking about a month each. I wrote the preface, introduction and everything else after the main content had been tech edited and was being copy edited.

I created a private repository on Bitbucket to host the book's source control in Git. The only reason I chose Bitbucket over GitHub was because Bitbucket offers free private repositories. It's a shame they have no plans to build a custom renderer for AsciiDoc.

I wrote the book using IntelliJ IDEA and used a combination of ./gradlew watch and Grunt with Browsersync to refresh my browser when changes were made.

Tech Editing
I sent my tech editors, Dennis Sharpe and Kile Niklawski, emails when I finished with a chapter. I gave them access to the book's repo, as well as the sample application's repo, and detailed how to access them. I made sure and documented how to build both projects in their README files. I asked Dennis and Kile to enter issues, or create branches and pull requests when they found problems. They entered a few issues on the first chapter, but responded via email after that. They didn't find many issues, so this process was good enough for me.

Copy Editing
Lawrence Nyveen copy-edited the book and was gracious enough to try my recommended process:

• Checkout the source code of the book from Git.
• Create a branch, make changes.
• Publish the branch, create a pull request.
• Have a conversation about the changes on the pull request, make more changes, merge pull request.

This process seemed to work very well and Laurie quickly learned how to work with Git. We both used AsciidocFX to edit and make changes. We used comments in the book's code to ask questions to each other. AsciidocFX worked quite well, though we did find we needed to add :imagesdir: images to chapter headers to get them to render images. Having problems with image rendering was not new, I had to create a symlink in the chapters directory to the images directory above it to get images to render in EPUB.

From the time Laurie started copy editing until he was finished was only a couple weeks.

Publishing
As I mentioned earlier, making the output look like InfoQ's mini-books was one of the biggest concerns with this book. InfoQ wanted to take the HTML (or PDF) version of the book, feed it into their desktop publishing program, and publish from there. I expressed my concerns in an email:

The JHipster project moves pretty fast, so it'll probably be a lot of work to pump out releases as quickly as they do. It's probably better to do a release per quarter with updated material. If you're going to reformat it every time we do a release, that could create a lot of work.

They agreed and mentioned the output from Asciidoctor was looking pretty good. They asked if I could make it match the standard InfoQ look and feel. I did some research, found out it might be possible, and went to work. It took me a week of research and a week of trial-and-error to produce the final product.

What's Next?
The good news is the first (1.0) version of the book is in production. I have not published 21-Points Health (the example application for the book) as an open source project, but I may in the future. For now, I hope to do my best to keep the book (and the app) up-to-date with JHipster releases. That may prove difficult, but we'll see.

One of the things I recommend in the book is to follow John Papa's Angular Style Guide. A recent pull request does this for JHipster. I think this is an excellent enhancement, but it'd also require me to rewrite many of the JavaScript sections of the book. It sounds like a daunting task, but at least it's a mini-book!

If you have any questions, comments or suggestions about writing with Asciidoctor or publishing with InfoQ, send them my way. My fastest responses will likely come from Twitter (@jhipster_book or @mraible). You can also leave a comment here, on jhipster-book.com, or post a question on Stack Overflow with the "jhipster-mini-book" tag.

P.S. If you live in Denver, there's a presentation on Asciidoctor by Tim Berglund and Cara Jo Miller tonight. I'll also be talking about JHipster at Devoxx next Wednesday.