From Idea to Print: Our Journey Writing an Elixir Book

If you’d have spoken to either of us 5 years ago and told us that we’d be published authors, we wouldn’t have believed you. After months of writing, editing, and refining, the first physical copies of our book - Engineering Elixir Applications - arrived in the post last week! Here’s one in all her glory with our cat, Runa (we had to bribe her to take this photo):

Publishing a book seems like such a mythical thing that “normal” people can’t do. But, in our experience, writing a book is actually a lot easier than you’d think. Once we worked up the courage to submit our proposal, things began falling into place (with a lot of hard work, of course). Now that we’re on the other side, we wanted to share our journey in the hope of making the process feel less daunting for others. After all, the more books out there, the better!

Why Did We Write the Book?

It was Josep’s idea to write the book. When working at Erlang Solutions, he made an internal course for new interns so that they could learn Phoenix, Elixir, Erlang, and how to deploy an application. After presenting the course to the CTO, Francesco Cesarini, he said to Josep: “This smells like a book!”. And so the cogs in Josep’s brain started turning…maybe it could be a book?

Originally, Josep thought about writing the book on his own. However, after sitting down together and talking through his plan, we both came to the conclusion that the process would be a lot smoother if we wrote it together. Josep would provide the basis of the technical knowledge and I would help him articulate the message we wanted to convey. I also had less experience with the technologies we were going to write about, and so could help tailor our explanations to a more beginner friendly audience. So as we were going to be splitting the work 50/50, it was only natural that we both be co-authors.

(On a side note, writing a book also takes up a lot of your weekends and free time, so it was also a great way to spend time together.)

When it came to starting to write the book, we didn’t know how to begin. Josep spoke to a friend, Manuel Rubio, who had contacts at PragProg. Through him, we connected with Sophie DeBenedetto who helped us with our book proposal. And as they say, the rest is history.

The Book Application Process

When applying to write a book, for PragProg at least, you have to submit a proposal. To help, PragProg gives you a proposal template that you can use which has the following prompts:

• About You
• What is Your Book About?
• Why Is Your Book Needed?
• A Rough Outline
• Promotional ideas
• A Writing Sample

Sophie was monumental in helping us complete our proposal. We seriously can’t say enough great things about her. She helped us refine the outline for the book and read through the first writing sample that we wrote, giving us a few pointers here and there on how to improve it. Without her help, our proposal definitely wouldn’t be as strong as it was, nor would the book look like what it does today.

As neither of us had written any content before, we decided that our writing sample would be what would become chapter 2 of our book: how to create issues and milestones in GitHub using Terraform.

We started writing our proposal in mid November of 2022. It took us about 2 and a bit months (with Christmas/New Year/Holidays in the middle) to finish it. We sent it off to PragProg at the end of January of 2023, and two weeks later they sent us a book contract to sign! In the contract, you agree a more concrete outline of the book, estimate the number of pages, and work out the royalty % of the authors (and if there is more than one author, how the % is split between them). Josep and I have a 50:50 split the 42% author royalties.

It was official, we were writing a book!

The Book Writing Process

After signing our contract, we were introduced to our wonderful development editor, Nicole Taché, in March 2023. A development editor is the day-to-day editor that will read each of your chapter drafts and ready the book for the more formal review processes that you have. Normally they do not have any prior knowledge of your topic; their main focus is on your writing style and making sure you haven’t left anything unexplained and your explanations are coherent. Your development editor is your first port of call for any questions that you have. We struck gold with Nicole, she’s the best. Amazingly kind, and great at her job. She has the most eagle-eye of anyone we’ve met.

PragProg’s Milestones

Throughout the book writing process, PragProg has certain milestones to keep books on track. These milestones are:

1. A copy review of 3 chapters for general writing style.
2. A technical review^^ of 50% of your book.
3. The BETA release++ of 50% of your book.
4. A technical review of the remaining 50% of your book (so that 100% of your book will have been technically reviewed).
5. A final production review where the final copy of the book is reviewed/edited and the indexing/bibliography is created.
6. A layout review once the feedback from your 2nd technical review has been applied. At this stage all of the content of the book will be fully finished. This layout review is to make sure the book looks good once printed and any content changes here have a knock on effect.
7. The final publication of your book (!!) where your book is sent to the printer and people can buy physical books.

^^ A technical review is where a group of technical reviewers (friends/people that understand the content of your book) will read the book (and ideally try the code) and give you feedback on the content.

++ The BETA release means that people will be able to buy an un-finished digital version of your book and give possible feedback. Any other chapters that you and your development editor jointly approve will be published in this BETA release. Note that this is not the final version of any of your chapters, and anyone buying the book knows that the content is subject to modification.

Sticking to a Writing Schedule

To keep up with these milestones we decided to write one chapter per month. We had 12 chapters to write, so we estimated that if all went well, we would hand in the first draft of the final chapter at the end of March 2024. We decided to leave the introduction as the last chapter we would write. We figured that if we already had all of the content written when going to write the introduction, then the introduction would write itself (and it pretty much did). In terms of the previously mentioned review milestones, our one-chapter-a-month goal meant that we could hopefully stick to these deadlines:

Now, at the beginning we mostly kept up with our one-chapter-a-month self imposed deadline. But, we didn’t factor in the (very welcomed) feedback on our initial drafts into our calculations and how implementing this would affect the “more official” internal/external reviews. Rather than sending our 3 chapter copy review off in June 2023, we sent it off in July 2023.

Our rhythm then started to slow down a bit in summer 2023. We took a week’s break in August 2024 because my sister got married, and we took on another customer at BEAMOps. We still managed to roughly keep up with our one-chapter-a-month deadline though. By December 2023 we had finished 9 chapters (only 1 behind schedule) and were preparing for our 50% technical review. We didn’t realise that preparing for the technical review would take as much work as it did. For it we had to collate our first 6 chapters, make sure they flowed properly and everything was properly formatted. The idea is that these reviewers review an accurate representation of the final book will look like. Although you can make content changes after this review, it’s not ideal as you want to make sure your ideas are peer-approved.

We sent off the 50% technical review in January 2024 and had received all of the feedback by mid-February. Then we moved onto readying the book for the BETA release. This meant addressing the tech review feedback, rewriting a few parts here and there, addressing any outstanding style feedback from Nicole, ensuring the images were of the correct quality and making sure the code in the code snippets fit in the margin of the book. The book was released in BETA in April 2024. April 10th to be exact. The BETA release included 6 chapters, chapters 2 through 7.

Releasing the book into BETA was great news. We sat at the top of the best seller list for a whole month! But unfortunately, concentrating on preparing the already written chapters for the BETA release affected our one-chapter-a-month goal. This was because, we decided, along with Nicole, to sideline writing new chapter content while getting the book out in BETA. We’re undecided as to whether that was the right call or not. On the one hand it was a good idea. It got us into BETA quicker, it allowed us to re-think some of the still-to-be-written chapters that were a bit more complex, and it was extremely motivating to see people buying our book. However, it did disrupt our rhythm a bit, and we found it hard to re-pick up our momentum of writing the new content.

The Final Stretch

The last first-draft of our book was handed in in May 2024. And after all of that feedback was addressed, we handed the book in for the 100% technical review in June 2024. We received the technical feedback mid July 2024 and handed the book in for its final production review later that same month. Whilst this was all happening, new BETA updates of our book were being published roughly once per month. For each new chapter we had to repeat the process of addressing any outstanding feedback, adding any content we felt was missing, readying the images and revising the code snippets.

We received the production review feedback in mid-October 2024 and implemented it that same week. The book was sent for its layout review in November 2024. And this is where we ran into a bit of a hiccup. We realised that we had to slightly change some of the book content in chapters 7, 10 and 12, as well as the structure of the code in the folder that you can download on the PragProg website. What we failed to realise, however, was the purpose of the layout review. We had assumed that it was only about image sizes, but it is in fact much more complex than that. The spaces between headings, inside the text of a paragraph etc. is all looked at and updated. This means that adding new content and forcing a page break in a different place has serious knock on effects. If we weren’t to make any of our changes, our book was scheduled to be released at the end of November 2024. However, PragProg were gracious enough to let us push our changes through. This meant that part of our layout review had to be restarted and re-scoped according to the other work that the layout review team had. Because of this, our publication was delayed by a few weeks.

Our book was (finally) published on December 18th 2024. Just in time for Christmas! We also received the great news that our book was the joint second highest selling book that PragProg had in 2024!

So What’s the Book About?

So after all this, what is the book actually about? The book is a one-stop-shop for learning how to deploy an Elixir application from development to production. We give introductory explanations to Terraform, Docker, GitHub Actions, Packer, and many more technologies. We go through the packaging of an application, CI/CD pipelines, remote infrastructure provisioning and automation, creating distributed Erlang clusters, autoscaling, and instrumentation. After having read the book, you’ll have a multinode Docker Swarm that’s distributed across multiple availability zones in AWS and that autoscales according to the average CPU usage of the servers hosting your application.

We made the book as it was a resource that we would have loved to have. And that’s what tech books are for. For sharing your knowledge and giving to someone else everything that you would have loved to have learnt. If you see a gap in the market of something that you would have loved to have read but doesn’t exist, then we highly encourage you to write it yourself.

Hopefully you can see from our journey that writing a book is a lot less daunting than it seems. Once you break it down into smaller steps - the proposal, a 3 chapter review, a 6 chapter review, a whole book review - the time really does fly by. And before you know it, you’ll have a fully written book. If you have an idea that you think could make a good book, drop us a message and we’d love to help you with your application!

That’s it from us this week. Thank you for reading and catch you in the next one. 💜