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.
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.
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.
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.
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.
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.
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.
Matt, thanks a lot for the great resources!
However, I think it's a must to release the source code for the 21 points app. I did some mistake(?) when creating the entities and gave up because I don't want to invest time to research my mistake.
I also would like to have at least step-by-step instructions for everything because I really just want to execute the tasks quickly.
But anyway it's a great effort from your side to provide this book!
Posted by Lars Fischer on November 04, 2015 at 08:23 AM MST #
Posted by Matt Raible on November 08, 2015 at 10:31 AM MST #
Thanks for the JHipster Mini-Book. It is a great help book.
I wanted to ask you about AngularJS 2.0. What do you think about the future of Angular? Should we stay with Angular or use another one.
Thanks, Matt. Keep up in your great work.
Posted by Viliam Kasala on November 25, 2015 at 02:30 AM MST #
Viliam: I think the future is bright for AngularJS! I think a lot of folks will continue to use Angular 1.x, even after 2.x reaches a stable release. However, I think people that try ES6 and TypeScript will really like it, so it its adoption will be gradual.
The JHipster project has stated that an Angular 2 option will be created once a stable version is released.
In the meantime, I think you should try to use John Papa's Style Guide when writing Angular 1.x apps. This will help you migrate to 2.x. JHipster is in the process of adopting it now.
Posted by Matt Raible on November 25, 2015 at 07:51 AM MST #
Posted by Harinath on December 14, 2015 at 04:00 AM MST #
Posted by Matt Raible on December 14, 2015 at 06:54 AM MST #
Posted by Daniel on April 19, 2016 at 08:08 AM MDT #
Thank you very much for this really valuable information, it's of great help for developers like me without much experience with jHipster.
Looking forward to other of your jHipster related posts!
Posted by Mikel Urkia on July 14, 2016 at 04:51 AM MDT #
Posted by Tom Hayden on December 07, 2016 at 01:06 PM MST #
Posted by Matt Raible on December 07, 2016 at 01:13 PM MST #