Writing "CMake Best Practices" - A writing journey
When Packt Publishing approached me in august 2021 with the idea of writing a book about CMake, I immediately was all for it. Ten months later I am mightily proud that “CMake Best Practices” finally hit the shelves. As this would be my first book, I had no idea what I was getting into when I signed the contract with Packt. The months of writing the book were among the most exhausting ones in my whole career and they were an emotional rollercoaster, but I also count them as one of my most valuable experiences. And finally seeing the book getting the first customer reviews really rocks. So how is it to write a book for Packt as a first-time author? In this article, I try to give a few insights into my writing journey.
CMake Best Practices - The book
How Packt gets books done
Packt Publishing capitalizes on the print-on-demand and digital market, so its mode of operation is geared towards a high output of technical literature in a very short time - and this shows in the way how they approach book projects. In my case, I was approached by an editor from Packt over LinkedIn and asked directly if I wanted to write a book about CMake. After a few days of thinking, I said yes and soon was paired up with my co-author-to-be. Being paired with a stranger for such a big project felt a bit weird, especially as there was very little effort by the people from Packt in introducing us to each other or helping us set up a productive work environment. We essentially got each other’s e-mail addresses and a brief bio and then it was up to us to figure out who writes which chapter and how to coordinate the work on the shared documents. We were lucky, that my co-author Mustafa and me have a similar writing style and that we agreed quickly on the overall content that we wanted to put into the book.
After the initial contact with the publishing product manager, the first thing we had to do was to write a pitch for the book, including a rough outline of the contents covered and a description of the target audience we wanted to reach. The senior editor from Packt would then use this pitch to push for an internal Go/No-Go decision and once we took this first hurdle, we had to write an outline of all the intended chapters. This included tentative titles for the sections and an estimated page count. It pays to put some extra effort into the outline, as this will become the central document from which the contract is drafted and from which the progress of the book will be measured. At this point, we authors also had to agree on who would write which chapters - this was used by Packt to evaluate who would get how much of the royalties in case the book would be eventually published. We intended to split the content roughly 50/50, so splitting the royalties evenly seemed only fair then. This would later cause a bit of grief on our side, as the first estimated page count per author was off quite a bit, but we could quickly resolve that. For Packt this page count is very important as the schedule is based on these numbers and we had quite some discussions with our editors about page count during writing. The main problem was that as first-time authors we had absolutely no clue how much space the information we could fit into a chapter would take. In the end, we had chapters that overrun the estimation twice and others that would end up being only a third of the estimated size.
The outline was then evaluated by Packt for another Go/No-Go decision and to draft out an approximate timeline for the project. Luckily we passed that stage as well and by this time we were offered a proper writing contract - up to this point, there was no formal working agreement or contract so if the book would not be published we would have worked for free up to that point. The contract signing was more or less uneventful and according to my research with other publishers is more or less what is to be expected as a first-time author. My co-author and I each got 8% royalties and roughly 1000$ writing fee, paid out upon timely completion of parts of the book. And then it was “go” for writing.
The writing slog
The actual writing of the book was done chapter by chapter, with each chapter being assigned to an author and having a predefined deadline for the first draft and final editing. Each chapter would go through the following stages:
- Write the first draft and create any code examples on github.
- Hand the first draft over to the main editor.
- After a few days, we would get the annotated document back and have a few days for corrections.
- Send the corrected document to the technical reviewers.
- After a few days to weeks get the annotated document back from the technical reviewers.
- Rewrite any parts and code examples that drew comments from the technical reviewers.
- Hand the corrected documents back to the editor.
- Receive a final draft to sign it off for production.
Although the process itself was straightforward, what bothered me a few times was that it was not intended to take extra iterations in this process. The process was tied closely to the project schedule and not delivering an edited chapter on a pre-agreed date would prompt questions and increase pressure from the project team at Packt. Especially for the more complex chapters, such as the one on dependency management and the one on testing, more than one round with the technical reviewers were needed. Fitting in an extra round with the editors and adapting the schedule proved to be difficult. Any such extra round meant that we would need to pick up the pace on writing later on. There was quite obviously a trade-off for Packt between pushing books as fast as possible and getting the quality right and sometimes I was left with the feeling that publishing on time was the more important factor. The quality of writing drops quite a bit, when writing under pressure and this showed in the number of issues brought up in the review which then again would mean more work fixing them and we would fall even farther behind schedule. In the end, we only managed to pick up the schedule again by spending some holidays writing the book.
Delivering chapters on time
Keeping the tight and rigid schedule meant was often demanding - even grueling - especially if done besides a full-time job. For me, it often meant getting up an hour earlier, writing a bit, sending the kids off to school, doing a full day of work, and putting another few hours into the book once the kids were asleep. Needless to say that this took quite some understanding from my family and some of my hobbies suffered quite a bit from this. If I ever write a book again I will either push harder for a more relaxed schedule or try to take some writing days off work.
One big advantage to defining a rough timeline for writing up front is that there is less danger of putting the book away when the writing stalls for whatever reason. The schedule was proposed early on by Packt based on the outline we drafted in pitching the book. Initially, they wanted two pages per day and it took a bit of haggling to get them to shift from that number. In the end, we used 1.5 pages a day (including weekends) as a basis for calculating the schedule. Still, a very is a very tough thing to do. Just writing the chapters might have worked, but on top of that, we needed to come up with easy-to-understand examples and especially later in the book there was always at least one chapter under review which needed additional time which was not reflected in the schedule. In the end, we barely managed to put out the book with only a little delay, but sometimes it felt that Packt took advantage of the fact that we first-time authors had no clue about how tough the writing process would be when we set up the schedule.
Competent reviewers are worth their weight in gold
Perhaps the biggest advantage for us was, that Packt brought some very competent and fast editors to the table. We would hand in the first draft of a chapter and a few days later we would get the document back with corrections, questions and annotations. I found it very pleasant and productive to work with the editors and technical reviewers. I would venture that having easy access to a team of editors and reviewers if probably the biggest advantage when working with a large publishing company.
The technical reviews were amongst the most helpful things to increase the quality of the book. Our reviewers were absolutely superb and very thorough when it came to checking the technical correctness of the book. They often came up with very good suggestions on how we could change examples or reshuffle the sections to make more sense. On the other hand, working with them was sometimes unnecessarily difficult because how the communication channels were set up. Of the four different technical reviewers that worked with us, only one was finally invited to our slack channel so we could interact directly with him. For the other three, we had no other means of communication than over the comments in the chapters or by mail-relay over our editors. Something that I know now was also not very well received by our technical reviewers.
Once most of the final drafts were done, there were some last finishing touches to be done. Writing author bios, acknowledgments blurb and various texts and summaries of the book to go on to the product page at Amazon and other stores. This was pretty straightforward and painless, but since the publishing date was fixed by this time this meant again keeping a very tight schedule. On the other hand here having a professional, big publishing house backing the book was a very big advantage, as most of the tedious small things like aligning the content with page breaks, and creating an index and a glossary were done by people at Packt.
Tooling and handling documents
One big downside from my view is that Packt wanted us to write the book Word and that all data exchange and versioning of the documents was done over SharePoint. Both tools are only halfway suited for such a heavy project - Especially if one is used to working with git and markdown, asciidoc or reStructuredText. The lack of a proper way to put code into Word was a major pain for me. If a review would take more than one turn or if a document passed through multiple hands tracking the changes in Word would become almost impossible. Since it was often unclear if we as authors or the senior editor were responsible to accept the suggestions. Working with SharePoint was a nightmare. SharePoint sucks at handling versions and documents would vanish without a trace because somebody was moving them somewhere and there sometimes would be multiple copies of different versions of the document lying around. Luckily we found most of the documents again but at least on one occasion changes were completely lost. For me, the choice of the toolset for such as technical book was one of the biggest disappointments and felt cumbersome and often distracting.
Would I do it again?
All in all, writing the book was a very cool experience and I am quite proud of what came out of it. Would I do it again? Yes, but I would probably either push for a more relaxed schedule, reduce my contribution or see if I can take some time off work and my other obligations to write the book. I think the writing process works reasonably well and has a high guarantee that books are going to be published and not left halfway through. There are a few things that I think could be improved to get more quality into the writing, first starting with facilitating closer collaboration between the technical reviewers and the authors. Being able to discuss examples and concepts with the technical reviewers before they go into the book would not just reduce the amount of rewriting needed but also ensure that the examples are understandable with as little context as possible.
Being paired up for such a large project with someone you do not know bears also quite a risk. I was lucky in the way that my co-author Mustafa and me mostly agreed on how we would write things and structure the code. But I can imagine that this might be quite difficult if there is no such fit. Added to this is that it is entirely up to the authors to establish a reliable communication channel, something that took us a while to figure out. It also pays if you talk early and frequently about your expectation of each other, i.e. how much you review each other’s work, and whether you do sparring sessions for the tougher chapters or not. This is one thing that we, unfortunately, neglected quite a bit as the pressure increased because we were late in delivering some of the chapters.
Nevertheless pairing up with a large publishing house such as Packt has many advantages - especially for first-time authors. I am sure that without the push and coordination from the people at Packt and the many additional resources such as editors and (technical) reviewers “CMake Best Practices” would still be unwritten. I underestimated how many people are involved in creating such a book and Packt’s ability to bring all the necessary skills together is very helpful. So, if I ever want to write another technical book, going with Packt again is definitively an option for me.