Sharing My Know-How on Writing Books with GitHub

I will share the know-how I've gained from writing over 10 books using GitHub. Most of the books I've written were doujinshi (self-published works) of several dozen pages created by just myself and an editor, but two of them were major works of several hundred pages that you would find in bookstores. Therefore, I believe this content will be useful to some extent for those who want to write a book in earnest.

First, an overview. Regarding the format for managing manuscripts, I wrote mine in Markdown because it's easy to preview on GitHub, but you should feel free to decide this based on your preference and what the publisher allows. Next, regarding how to share data with stakeholders such as editors and reviewers, it's as simple as getting their GitHub accounts and adding them as collaborators. Generally, the repository for managing the manuscript would likely be set to private.

There are various stages in bookmaking, but I roughly categorize them as follows:

1. Create a "policy" while consulting with stakeholders, defining "who this book is for and what value it aims to provide."
2. Write the manuscript all at once on your own to give it some shape.
3. Have the drafted manuscript reviewed by various people to polish it.
4. Pass the polished manuscript on to the subsequent DTP (Desktop Publishing) process. From this point forward, the work is primarily handled by the publisher and the editor, and no drastic changes are made.

I manage only stages 1, 2, and 3 on GitHub, and for stage 4, I leave almost everything to the publisher, with the exception of author proofreading. It might be possible to manage the DTP process and beyond on GitHub if you work hard at it, including negotiations with the publisher, but I haven't done so, and since I lack knowledge in this area, I have no intention of doing it in the future.

If you don't establish stage 1 properly, you will struggle in the subsequent stages. Specifically, you will find yourself constantly agonizing over questions like, "What on earth am I writing?", "Where is the goal?", and "Even if I finish it, will I have achieved the objective?"

In stage 2, it becomes important to realize that "a book manuscript is not code." In the case of code, there are best practices such as "combining one change into one logical unit" or "keeping commit messages to a minimum while writing the necessary why," but these do not apply to manuscripts. I occasionally receive advice from the editor, but for the most part, it is a solitary task. Although there are some exceptions, such as when working on the overall structure, I push to the main branch whenever I pause my work, regardless of whether it's a good stopping point. Even if I were to create a branch, while I'm fiddling with the structure this way and that, there's a high possibility of changes conflicting with other branches, so there isn't much to gain from doing so. Commit messages are haphazard, like "update" or "fix," because the changes aren't organized into logical units in the first place.

Things change from stage 3. Specifically, at this stage, the document is in a unified form regardless of its quality, and the number of stakeholders such as reviewers has increased. From here on, issues and Pull Requests (PRs) become active. Basically, I receive a set of comments from reviewers and repeat the process of addressing those points. For obvious corrections, I have them issue a PR and then merge it. If there is a counter-argument, I write it in the PR message and either have it removed from the changes or change the method of modification. For things where judgment may vary depending on the person, I have an issue opened for discussion, and once the policy is finalized, I create a PR corresponding to the issue and merge it (sometimes the person who pointed it out creates the PR). If the policy decision in stage 1 isn't settled firmly, you will end up wandering like a weathercock, merging PRs belonging to "matters of preference" just as they are suggested, only to merge another PR from someone else also based on "matters of preference," and so on.

I haven't always been able to do things properly like the above from the start, but I have now settled into this style. For those who want to write a book in the future, I hope this article is of some use. Finally, I don't think for a moment that my method is the one and only correct answer, so I would be happy if you could also share your styles with me.