Versioned Writing

Over the past several years, there have been numerous discussions of versioned writing in various places. Unfortunately, these discussions usually get wrapped up in discussions of shiny tools or specific writing formats.

As the co-founder of a shiny tool (Leanpub) and the creator of a specific writing format (Markua), I’m part of the problem.

But these discussions always miss the most important thing.

To do versioned writing well, the most important thing is a human-readable, plain text writing format.

Actually, that’s the only important thing.

Nothing else comes close. Leanpub, Markua, Markdown, none of it. End of discussion.

Now, the easiest way to make a human-readable plain text writing format is to make a human-writeable plain text writing format.

Markdown / Markua is my preference, obviously, and Leanpub is built on that. Other people prefer AsciiDoc or other formats.

But the important thing is the existence of a human-readable, human-writeable, plain text format. The tooling is secondary.

Any tool (e.g. git) or web app (e.g. GitHub) can diff versions of plain text files acceptably well.

No tool can diff versions of binary files acceptably well. Furthermore, even if it could, it would still be unacceptable because of lock in. No one would consider Track Changes in Word an acceptable way to do versioning of one’s own work — let alone to enable scholarship, say a hundred years later.

So, that’s it. If you want to do versioned writing, here’s how you do it:

1. Choose the plain text writing format that makes you happy. I recommend Markua, which is based on Markdown. Or, if you don’t want to write in plain text, use a tool which saves the work in plain text. Leanpub has a visual editor which saves your work in the Markua plain text format.
2. Choose the writing and publishing platform that makes you happy. I recommend Leanpub, since I co-founded it and since it’s awesome. Leanpub is based on the idea of Lean Publishing, which is the act of publishing an in-progress book using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. We pay 90% minus 50 cents royalties.
3. Store your work in a version control system. I recommend git. If you use Leanpub, we automatically save a version in git every time you preview or publish, and you can click a link to download it at any time. (So, even if you are not a programmer, you still benefit from programmer-quality versioning tool like git, without having to use them.)
4. If you want to compare versions of your work, use whatever diff tools make you happy. On Mac, there’s a tool called FileMerge. On Windows, there’s a better tool called WinMerge. Since you’ve been storing your work in a plain text format, there’s zero lock in.
5. Write. All the other things aren’t important if you don’t do this. And to do it well, use platforms, formats and tooling that let you focus on this — and nothing else.