Matt RaibleMatt Raible is a Java Champion and Developer Advocate at Okta. developer.okta.com

The JHipster Mini-Book The JHipster Mini-Book is a guide to getting started with hip technologies today: Angular, Bootstrap, and Spring Boot. All of these frameworks are wrapped up in an easy-to-use project called JHipster.

This book shows you how to build an app with JHipster, and guides you through the plethora of tools, techniques and options you can use. Furthermore, it explains the UI and API building blocks so you understand the underpinnings of your great application.

For book updates, follow @jhipster-book on Twitter.

10+ YEARS


Over 10 years ago, I wrote my first blog post. Since then, I've authored books, had kids, traveled the world, found Trish and blogged about it all.

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

The JHipster Mini-Book 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.

Posted in Java at Nov 03 2015, 10:13:40 AM MST 10 Comments
Comments:

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 #

Thanks for the feedback Lars. I'll work on getting 21-Points released to open source this week.

Posted by Matt Raible on November 08, 2015 at 10:31 AM MST #

Hi Matt,

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 #

The JHipster Mini-Book Link is not working at http://www.infoq.com/minibooks/jhipster-mini-book. Can you please provide working link to download JHipster Mini-Book.

Posted by Harinath on December 14, 2015 at 04:00 AM MST #

Harinath: I just tried this link and was able to download the PDF without any issues.

Posted by Matt Raible on December 14, 2015 at 06:54 AM MST #

Its easy if your registered on infoQ

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 #

I cannot upload the .epub file to Google Play Books due to validation error (http://validator.idpf.org/ >> https://github.com/IDPF/epubcheck/)

Posted by Tom Hayden on December 07, 2016 at 01:06 PM MST #

Hi Tom. I just tried v2.0 of the JHipster Mini-Book on http://validator.idpf.org/ and it fails because the .epub is 18.4MB and they only allow 10MB or less. It does work with iBooks; not sure about Google Play Books. If you can provide further instructions on how to validate it, I'd be happy to take a look.

Posted by Matt Raible on December 07, 2016 at 01:13 PM MST #

Post a Comment:
  • HTML Syntax: Allowed