As developers, we have written the book with the same approach we usually take for producing software:

• version control-friendly source files
• automated testing and validation
• continuous integration

Markdown format

We were asked by Packt, our publisher, to write the drafts in Microsoft Word and use the styles dictated by their templates.

From the very beginning, we realised that this was not a very convenient way to work as a distributed team of two writers.

Word is an excellent format for solo writing, but it's a nightmare to store Word documents in any version control system. We knew it was going to lead us to a lot of frustration. So, we decided to take a simpler, saner approach: Markdown and text files. No more DOCX files that can only be edited from the over-bloated interface of a modern word processor.

The book is completely written in the Markdown format, which is easy to read, write and automate. To keep our publisher happy, we still had to produce Word documents out of the Markdown files. We ended up writing a Markdown to Word converter in Groovy, leveraging the excellent libraries available in Java (e.g. pegdown for parsing Markdown syntax and docx4j for creating Word documents).

The first version of the converter was just using default Word styles, and, obviously, publisher complained about it, but we quickly adjusted the generation process to match their Word template.

Markdown, after all, is just text files, and we enjoyed the same benefits that we normally get when working with source code. The most important of them being the easiness of merging file, which allowed us to work at the same time on the same content. Furthermore, now we could use any text editor on any device (even on a smart-phone) to edit the book. It felt much more natural (and cheaper!) than being dependent on a legal copy of Microsoft Word to be installed on our laptops.

Naturally, Markdown does not offer the multitude of features of a modern Word processor, but we found the zen-like simplicity of Markdown more than enough for our needs. In addition, Markdown (and the pegdown library that we used for parsing it) is easily extensible with additional styles. By the time the book was close to its final shape, we had extended the converter to support the complex Packt formatting styles, such as notice and information boxes, screen texts and keywords.

Quality control

Markdown, thanks to its straightforwardness, is easier to automate. For example, inside our Markdown-to-Word converter, we've implemented several validators and rules, which are close to impossible to implement in Word. Here are some examples of those rules:

• Each recipe should contain at least How it works... section.
• Each recipe should only contain allowed headers ( Getting ready..., How to do it..., How it works... etc.).
• There should be at least 1 paragraph of text between headers, code blocks or images.
• Introduction section should contain "in this recipe"-like phrase.
• and many more other rules...

Also, there were some very Groovy-specific rule sets that we applied to the code snippets appearing in the book:

• Each Groovy snippet was compiled upon build to catch any complication errors.
• Each Groovy snippet was passed through CodeNarc - Groovy static code analysis tool - to find any standard Groovy code styling and naming issues (we also talk about that tool in the book).

Additionally, text of the book was checked for spelling and grammar problems with the help of existing Java libraries.

Continuous integration

The conversion from Markdown to .DOCX and the quality control tasks mentioned above have been organised into a build process (driven by Gradle) and automated via our favorite continuous integration server - Jenkins.

On each chapter build, all the rule violations were collected into a report that was visible to both of us, so that we could see the current state of the chapter and the book as a whole. Once again, we have capitalised on our experience as developers and brought some software development best practices to the book editing and publishing world. This process resulted in blazing fast feedback for, us, the authors and a laser-accurate status for the publisher.

The above report is another example of the kind of quality control that we applied to the book. The report was generated with the help of Jenkins Warnings Plugin, which was configured to catch book specific warnings from the build output.

To keep tracks of the many TODOs in the book's drafts, we collected and monitored them with the help of the Jenkins Task Scanner Plugin.

Conclusion

We hope you enjoyed this "behind the scenes" report of the process that brought us to create a brand new strategy for editing and controlling the quality of a book.