Writing a book in the age of open source
The power of engineering applied to writing
About a year ago, and I set out to write our first book. A book for aspiring Engineering Managers.
We quickly realized that writing was a much larger undertaking than we had anticipated. We also found ourselves overwhelmed by the numerous tools used in the industry.
As engineering managers, we knew one thing for certain: we wanted to optimize the process to make it as seamless as possible, allowing us to focus solely on the content.
Since committing to this colossal task, we've conducted extensive research on the best tools and ways to improve our workflow. In our quest for efficiency, we've discovered various methods that others use to achieve the same goal.
In this article, we will share our journey through various tools and explain how we chose Asciidoc as our "chisel." We will also discuss the tools we've developed to quickly and efficiently transform our content into a publishable asset.
Preparation
As you can imagine, writing a book involves a significant amount of time spent with your chosen writing tools. Your desk, chair, keyboard, and software all contribute to how smooth (or challenging) your writing experience will be.
If you select a tool with several shortcomings—such as an inability to layout the book as desired—a significant portion of your time will be spent overcoming those challenges.
Software
We did extensive preliminary research before we started where we talked to a couple of friends and family to ask about the tools they used to write their books in.
The most common answer was; Microsoft Word
We knew up front that, whatever solution we picked, it should be accessible, easy-to-use, free and preferably open-source. That way, we would be able to have a repeatable and shareable setup. So Microsoft Word was a no-go for us.
Plain old Google Docs
Google Docs was the next best choice. A fair bit of publishing companies as well as many authors do use it. It has the all the features which you would expect from a text editor and it’s free (if you exclude the fact that your data is being processed by a tech giant).
Google Docs does not provide a great experience when it comes to writing but it definitely is accessible. It’s very easy to just pop open your browser and start typing.
Markdown
As developers, quite often, we make use of Markdown to write our READMEs. This has given us a certain affinity with the language. We are engineers after all!
Therefore, after having experimented with Google Docs, we quickly decided that the workflow we have to manage our READMEs would work way better. We get to use our favorite text editor (Neovim, Visual Studio Code, etc.) which makes it very easy-to-use and accessible. Most editors are free and quite few of them are also open source.
Markdown does satisfy all the conditions we initially had in mind.
What we didn’t know at the time, however, is the fact that, to self-publish a book, it is not sufficient to just have the content ready. The book needs to be laid out. It has to adhere to common conventions about structure, such as front and back matters, book index, table of content. All of which, is very difficult to do in Markdown, since it’s not really built for such tasks.
Asciidoc
Frustrated by Markdown's limitations, we found ourselves searching once again for a better solution—something that could offer the simplicity of Markdown while also providing the advanced features needed to prepare text for publication.
That's when we discovered Asciidoc.
Asciidoc offers a rich feature set, encompassing everything you need to write a book. It includes not just the basics but also advanced tools like index generation and book covers. Additionally, Asciidoctor enhances the experience with a robust suite of publishing tools.
All the way from custom type faces (allowing us to use our favourite typefaces from Connary Fagen) to being able to easily generate the front and back matter, including the covers as well as a index.
LaTeX
We also considered another option: LaTeX. While LaTeX would have certainly provided the flexibility we needed (and more), it would come at the expense of accessibility.
The memory of countless hours spent during university writing our first scientific paper with LaTeX quickly reminded us why it wasn't the right choice for this project. We decided to look elsewhere.
Hardware
You'll spend most of your time typing, and before long, your backspace key might start wearing out. That's why we strongly recommend investing in the right setup. A proper desk that supports good posture will help you work more efficiently and reduce the risk of injury.
Keyboard
One of the most important components of the equation is your keyboard. prefers to use a ZSA Voyager, which allows him to have an open posture thanks to the split form factor. It also allows him to spend less energy moving his fingers around the board, keeping his wrists happy.
Desk/Chair
Where you sit or stand is as important (if not more) than your keyboard. is more old school in the sense that he prefers to sit whilst writing. But then, he uses a more active chair which allows him to not sink and the HÅG Capisco is his sitting of choice.
Writing
Now that we have our tools set up, we can finally dive into the material!
The structure
Most books consist of three main sections:
the front matter
the body
the back matter
Front matter
The front matter contains all the such as the colophon (information about the publisher), dedication (“look mom, I wrote a book”), and preface. The exact sections depend on the book and what the author would like to have. Regardless of what the author wants, there will always be some content preceding the body. These are just a couple of examples of things you could consider having in your front matter.
Body
This is the actual book. You can structure this the way you want. You can have as many chapters as you’d like.
Back matter
The back matter could contain a short biography of the author. Or maybe an index in which you can showcase the important words that are used across the book, and much more.
Once you put all of the above together, you will end with a structure which looks like the following
Publishing
After having set up our tooling, we extracted the bits’n’pieces which, we believe, could be used by anyone else who also would like to take a stab at writing a book. Check letterpress, our open-source project, to help you Gutenberg the 💩 out of your book.
Letterpress will provide you with a devcontainers, allowing you to get started without having to install anything on your computer.
It will also provide you with a backbone structure and a GitHub workflow which will enable you to generate a PDF as well as an EPUB, ready to submit to your preferred self-publishing platform (Gumroad, Leanpub, Amazon KDP, etc.).
Why would you ever get into it
One of the most fulfilling experiences in life is contributing to the ever-growing foundation of knowledge that has been built over generations. The greatest satisfaction comes from knowing that you have helped others with the wisdom you've gained.
Furthermore, knowing that you can learn something really well only if you try to teach it. Writing a book is no different. Going from an abstract thought (which almost always will feel brilliant in your head) to a concrete sentence requires a surprisingly huge amount work. The sheer amount of research you’ll have to do to be able to say to yourself that you understand a topic well enough to be able to talk about it to others. It’s the best learning experience one can ever have.
Eventually, if all goes well, you might also be able to earn some cents with your writing. Have a look at these two successful others and their experience into the economics of writing, to see what it really looks like. Gregor Hohpe1’s great article around the economics of writing technical books and another from Martin Kleppman2 discussing whether or not it is worth publishing a book.
Conclusion
What are you waiting for? If you feel you have something to share with the world, all you need is a laptop and you can start contributing to the accumulated knowledge of humankind.