Documents ≠ Programs mckinley.cc Home Blog Computers

---

Documents ≠ Programs

August 31st, 2021

I've recently become active again on twtxt.net, the platform that puts the "social" in "anti-social social media". There is a lot of intelligent discussion to be had there, and for the past couple days a discussion has been going on about technology buzzwords and, later, unnecessary complexity on websites. I was asked to clarify my position and, rather than try to fit it within the (admittedly quite generous) character limit, I figured it would be best to state my argument here, on my website, where I can ramble as much as I want. I get a free blog post out of it, too.

One of my biggest problems with the Web today is the lack of separation between documents and "apps". They are not the same thing, and confusing them can (and does) lead to real-world problems. The page you're reading right now is a document. It has been sent to your computer over the network in its complete form along with a non-essential support file to dictate how the page looks. It is the job of your favorite Web browser to parse my document and display it on your screen. This was the original vision of the Web.

Over time, it has become easier and easier to provide the visitors of your website an interactive experience. It can be very useful to run certain programs in the browser. In a lot of cases, however, the same technologies are used for documents. If your page includes a few non-essential scripts to do different things on the page, that isn't a problem. The document itself is still readable in a wide variety of programs and formats, regardless of support for those scripts.

It is when you start using special code to "build" the document on the fly that the problem arises. On the server side, this makes it more difficult to maintain the site or move it to a new server. You can even run into serious security flaws, all because your documents have become executable. Your serverless, headless, Micropub-powered personal website is unreliable precisely because you chose to introduce unnecessary complexity. Just use a static site generator like mkws and call it a day.

On the client side, you get compatibility issues and vast inefficiency. In order to view the document, you must have a new or advanced enough Web browser capable of running a (probably poorly written) script to fetch the document and put it on the screen. You must also choose to allow the owner of that website to execute arbitrary code on your computer. Many Tor users, for example, disable JavaScript for security reasons. They wouldn't be able to use that website.

Furthermore, you're recreating functions of the browser almost immediately. There is no need to do that. The user is already running a program that can do everything your code does faster. All you have to do is put the content in the right format and it's all handled for you.

Here's a recent example of a website, made up of documents, that decided to re-invent the wheel: https://slc.is/. A post from that site was close to the top of Hacker News yesterday. Not only does it require over 200 kilobytes of JavaScript to put text on the screen, most of it is external JavaScript, served from a CDN. The buttons on the top of the screen don't even do anything without it. They are h2 tags, for some reason, and they require JavaScript to implement hyperlinking functionality. The user can't even see where the links go by hovering over them with his mouse. Why was it designed this way? I couldn't tell you. It reminds me of a quote:

"An idiot admires complexity, a genius admires simplicity."
— Terry A. Davis

The original purpose of the Web was to be a set of protocols and formats used for the purpose of publishing documents. Despite constant updates and additions, it still works exceedingly well for this purpose. Besides, our documents haven't changed much. Like most websites, mckinley.cc doesn't need much more than basic formatting and hyperlinks, so why shouldn't it work well on NCSA Mosaic 2.7?

On-the-fly "building" of documents is, quite literally, fixing something that is not broken. Whether its being done on the server or the client it's inefficient, introduces unnecessary bugs, and makes your website more difficult to keep around as a result. I'll end with my original claim: If your personal website turns into an "app", you're doing it wrong.