Article reposted from the Abuse of Notation blog.
It is a well-known engineering principle, that you should always use the weakest technology capable of solving your problem - the weakest technology is likely the cheapest, easiest to maintain, extend or replace and there are no sane arguments for using anything else.
The main problem with this principle is marketing - few people would sell you a 10$ product that can solve your problem for ever, when they can sell you a 1000$ product, with 10$ per month maintenance cost, that will become obsolete after 10 years. If you listen to the “experts” you would likely end up not with the simplest, but with the most advanced technology.
And with software the situation is particularly bad, because the simplest technologies often cost zero, and so they have zero marketing budget. And since nobody would be benefiting from convincing you to use something that does not cost anything, nobody is actively selling those. In this post, I will try to fill that gap by reviewing some technologies for web publishing that are based on plain text and putting forward their benefits. Read on to understand why and how you should write everything you write in plain text files and self-publish them on your own website.
The problem of text is one of those problems where the simplest of all solutions works great - plain text files do the job. I’ve yet to see a use-case where considering any other technology is worth it.
And similar is the case with simple static HTML websites - a simple static page is better than all publishing platforms that can ever be created.
Anything you write and that you want to last should be put on plain text files.
But wait, doesn’t working in plain text require you to learn some complex markup languages where you have to learn some cryptic commands just to bold your text? Well, not entirely. For example there is Markdown, which is pretty simple. Here is how it looks:
Here is a heading
===
Here is a paragraph.
Here is another one.
You can also put *emphasis* on words.
And insert [links](https://boris-marinov.github.io).
You would realize that the paragraph above contains everything you need to know for most books and blog posts. Other styling (tables, quotes, etc.) are equally easy to do, and once you learn the basics you would find that writing markdown is faster than applying styling by using the mouse.
And also, all my blog posts exist as readable text files. Here is the text file for this post.
While I can write a blog post, or even a whole book in notepad, but there is no reason to do so - there are thousands of quality text editors that will do a better job. There is no wrong answer as to which to use (except emacs :DDD.) And because you are using an open markup format, you can try them all.
The one I use is called vim, but since it takes time to getting used to I won’t be preaching it to you (you can click the link to read all about why I use it.) A more beginner-friendly editor is Sublime text, for example. You can even get a Word-style editor that supports markdown or the markup format that you use.
If you use Word for big texts, you probably have used some kind of version control. For text files, we have git which is the same thing, except a thousand times more powerful e.g. you can go back as far as you like, you can create different branches, where different people make different changes, you can merge several different versions of a file into one automatically. As with text editors, there are a thousand interfaces for working with git. And a thousand places where you can host your project, publicly or privately.
If you don’t like markdown, there are many other markup format that you can use. And there is this tool called Pandoc that allows you to convert any of them to any other.
Pandoc can also convert a markdown document to a lot of different output formats - you can generate HTML for your website, you can generate an epub book that you can read in your e-reader or sell on Amazon or something. You can even generate Microsoft Word files, if you are a masochist.
Once you author some things on markdown, you might want to publish them, for example on the web. For this you have a lot of options: there is HTML via Pandoc, there might be some blog platforms that support markdown, but a lot cooler thing that you can do is to create your very own blog or website. For this there are programs called static website generators that do just that - create websites from a bunch of markdown files. Jekyll is the one that I use. It’s cool - you can create sections and books by putting files in different directories, there are ready-made themes that you can use, and you can tweak them if you know some HTML.
Finally after you own a website you just have to host it somewhere. You can buy hosting, and have a very own domain name. Or, if you don’t want to spend money, you can just deploy it to some static file hosting platform of your choice like Github pages. Github pages is very easy to use because it is integrated with Jekyll and git which makes the workflow very easy:
You just create a new project in Github and enable Jekyll support. As the name suggests, Github projects are actually git project which can be synchronized with some folders on your local drive via any Git software. And if you don’t want to deal with local files, you can author texts from the Github page directly. If you want to start right away, you can use a pre-made theme. If you like the theme I use for my books, you can check an article and the code that I use for my books.
My first blog was in blogspot. One day, I accidentally deleted it.
Then I made a blog in wordpress.com- just checked it, it’s still there, except that all images are dead.
Then I had a custom Wordpress website with a domain name and all, but I decided to remove it.
I authored my first book in Adobe InDesign because I wanted it to look good (and no, you cannot do that in Word.)
I would never use any of these technologies and platforms.
Firstly, the thing with the deleting - yeah, I might be an idiot, but the same thing can happen if the platform deletes your account without notice. That can’t happen with git, as I can synchronize all my files with my hard-drive of all my computers and re-upload them. And I cannot accidentally delete individual files either, because of the infinite version control.
Second, migrating to other platforms - if I want to export some of the genius writing I did as a teenager, from Wordpress.com to some other platform I cannot do that now. With static websites, I can switch to a different platform in a matter of seconds without losing any of my content.
Book publishing - I can do that from markdown in a number of ways. For my Category Theory book, I exported the files to LaTex using Pandoc. I can export directly to pdf using the same program, or even in Word (if I was mad.)
And last but not least, even when the Internet dies the world ends and we are back to using floppy disks, I will still have the original text files.