Writing a book
Here are some lessons I learned writing the German-language O'Reilly book about internet memes:
- Write everything in reStructuredText. RST looks similar to Markdown, but has a lot more features and a defined specification without ambiguities. RST processors may not follow the specification at times, but it is clear how a document should look. The author of Pandoc fixes layout bugs quickly. The Sphinx document processing system can export to HTML, EPUB, PDF, LaTeX and many other formats.
- Use Git even if you write alone. The web interface for our repository and Sparkleshare – a DropBox-like interface for Git – helped a lot with reviews. Gitstats helped me to find out that crunchtime always led to days of writer's block and helped me gauge how much text I could write in a sustained manner.
- Save source materials for later. I investigated the origins of one of the first lolcats (Happy Cat, first mentioned in promotional materials of Russian distributors for the Happy Cat cat food brand), but lost some emails related to the investigation. Similarly, footnotes in our printed book are exhibiting link rot. This could have been prevented by importing all source materials into the Git repository and making sure all web pages referenced are archived in the Wayback Machine. The Sphinx document processing system has a feature to check all URLs in an RST document for availability.
- Use the text editor you know. Do not learn a new editor for the project if you are already comfortable with one. I used GNU Emacs while my co-author used GNU nano; we never had any problems due to that.
- Tell others about your work. Me any my co-author worked remotely for the most time. Each evening we had a short chat about what each of us finished during the day, what we were working on, and what plans we had for the next few days. At least for me, telling someone else what I did boosted my motivation; having such a routine process helped me to overcome writer's block.
- Know your writing mode. There seem to be at least two different writing modes: I think a long time about what I want to write and then write, making a few cosmetic changes later; my co-author writes a rough draft and then refines it with each pass. This means that my text is always of the same quality, but he always meet deadlines. Using Gitstats, we found he wrote around twice the amount of text as I did, as he re-wrote almost everything at least once. We had no problems with this because we allocated who was responsible for each chapter in the beginning.
- Do not change your workflow. Process changes mid-way or at the end of a project often lead to more stress than it is worth. Writing using RST and Git worked well, but the publisher wanted our text as multiple ODT files and sent it back as a layouted PDF that we had to annotate. There seemed to be no software to merge two annotated PDFs, so I quickly hacked up something with Ghostscript. Creating changes in this way felt very stressful. Much later our editor told me that each one of our around 1000 annotations was apparently faxed to the layouter.
- Get a proper advance. An advance should at least cover your expenses for the time you write the book. You will most likely not make much money with your book – even if it is good and about a popular topic. Three years after our book has been published, only around 15 copies are sold each quarter; I suspect it might be one university course using it as classroom material. We did not ask the publisher for an advance and I think that was an error.
- Insist on free licensing. We told O'Reilly we would only accept a contract with a provision that the book would be CC BY-NC-SA and the licensing would switch to CC BY-SA (same as Wikipedia) as soon as O'Reilly stops selling the book. Now that the German section of O'Reilly is closed the book is still sold, but by another company that uses the O'Reilly imprint. Others authors told me beforehand that getting a publisher to agree to free licensing would be impossible.
- Give out specimen copies. Free books are some of your best promotion materials in terms of effort vs results. O'Reilly did not do much to promote our book, but they did provide us with copies. We probably should have asked for more and sent out more.
- Do not neglect your loved ones. I regret not having spent more time with the ex-girlfriends I was together with during the time I wrote the book.