Continuously Building a Book

I’m thrilled to announce the availability of a mini-book about Eclipse Vert.x. This book focuses on the development of reactive microservices in Java and covers reactive systems and reactive programming.

Writing a book, even for a mini-book is a tough task. While writing code and writing a book are very different experiences, you can apply the same process and good practice. I would like to list a couple of tips I’ve used to make the writing a bit easier.

1 - Write your text using Markdown or AsciiDoc

I’ve used AsciiDoc, but Markdown is great too. Using these syntaxes lets you focus on your writing and not on the “style”. The style (font, size) comes later. You can write your text using any text editor. Typically, I’ve used Visual Studio Code to write the complete book. It proposes a “distraction free” mode very useful to stay focused.

2 - Put your “sources” on a source management control system

One of the main advantages writing your book using AsciiDoc or Markdown is the textual representation. So, it’s easy to put your text on source control, check differences, follow the progress, create branches, and use pull requests. I’ve used Git, initially using Bitbucket and then switched to the Git repository provided by the O’Reilly Atlas tool.

3 - No code in your sources

If you write a technical book, you typically insert source code in your book. Don’t write this source code in the text directly. It’s error-prone and it may contain mistakes. Externalize your code, and build it as any regular project. With AsciiDoc, you can use the include directive to insert the code snippet and manage indentation.

4 - Tests your code

Externalizing your code is not enough, you need to test it too. Ensure that your code does what it is expected to do. Writing a few unit tests checking your code snippet ensures it does the right thing and enables refactoring and continuous improvement.

5 - Reproducible build and continuous integration

Provide a reproducible build to create the different output format of your book. I use Apache Maven to build my source code and the book itself, but there are many other ways. Having an automated build mechanism enables continuous integration. You can ensure that your book always builds and your reviewers can easily get the latest version.

In other words, apply the same process you are using for your regular source code for a book:

• Write source
• Use a source management control
• Implement tests
• Provide a reproducible build process
• Do continuous integration

Download the Eclipse Vert.x cheat sheet, this cheat sheet provides step by step details to let you create your apps the way you want to.