We Designed TigerBeetle's Docs from Scratch

I think this is a fun thing for TigerBeetle to do, but I'm pretty skeptical that this was a good engineering decision.

And it's fine to make non-optimal engineering decisions for fun, but the top reason in the article should be, "Because we thought it would be fun to code a docs site from scratch."

This post reminds me a lot of an article I read on HN about a year ago and can't find now, but the author was explaining how so many organizations end up investing humongous amounts of effort rolling their own databases from scratch because none of the off-the-shelf solutions meet all their requirements. But in most of these cases, it's because some of the "requirements" were actually "nice-to-haves" and they could have gotten by fine with an off-the-shelf database, but they talked themselves into building one from scratch.

A lot of the justifications here feel pretty weak:

- Didn't want to use a complicated React app? Use Hugo or Pelican or Eleventy.

- Wanted nice reading experience? Replace the default CSS in any SSG.

- Want a nice search experience? Theirs looks good, but is probably also achievable in off-the-shelf SSGs and is probably not worth rolling their own docs site from scratch.

>We employed a Content Security Policy to prevent Cross Site Scripting (XSS) as defense-in-depth, in case a seemingly friendly PR contains some innocent looking MathML. This MathML could contain obfuscated code that would run in the user’s browser. CSP prevents any unwanted inline scripts from running and keeps our users safer.

This was the silliest reason of all. Who's XSS'ing a docs site through obfuscated markup contributions? That sounds pretty difficult to achieve in the first place, and then what's the reward for achieving XSS on TigerBeetle's docs site? There's no valuable data there. At worst, you'd mine tiny amounts of crypto in a serviceworker. But also, you can mitigate this risk in lots of ways that don't involve rolling your own docs site.

Edit: They don't seem to actually be using CSP at all: https://gist.github.com/mtlynch/92c991cfe48652feee491d4f4652...

Edit2: Nevermind, they actually do but in HTML. Hat tip to pfg_.

To evaluate this as your are describing, you must reveal your estimate of the workload of what Tiger Beetle has done to roll their own docs. If it took them 5 minutes, for instance, the calculus is far different than if it took 5 years. Plus you must compare that time estimate to their other priorities to estimate the opportunity cost, something that you simply can not do accurately from the outside looking in.

And we must estimate the potential future value of what Tiger Beetle has done here. I value "no dependencies" pretty deeply and I can see how Tiger Beetle values it supremely. I don't see how you can hand waive it away so easily.

To assert that you don't believe Tiger Beetle at their word here is deeply disrespectful imo.

>To evaluate this as your are describing, you must reveal your estimate of the workload of what Tiger Beetle has done to roll their own docs. If it took them 5 minutes, for instance, the calculus is far different than if it took 5 years. Plus you must compare that time estimate to their other priorities to estimate the opportunity cost, something that you simply can not do accurately from the outside looking in.

I don't need them to reveal their numbers to me to offer my critique, as I think few people would argue that the upfront cost of rolling your own docs site could possibly be lower than the cost of deploying an off-the-shelf solution like Hugo.

I think where reasonable people might disagree is about the total cost of ownership of Hugo vs. the home-rolled solution over five years, but I'd find it surprising if home-rolled solution wins.

>To assert that you don't believe Tiger Beetle at their word here is deeply disrespectful imo.

Where did I say that I doubt TigerBeetle's claims? I disagree with the justifications in the blog post, but it's a difference of opinion, not a question of facts.

They published this blog post, and this is HN, so I think it's well within the community standards to offer a respectful critique.

> I think few people would argue that the upfront cost of rolling your own docs site could possibly be lower than the cost of deploying an off-the-shelf solution like Hugo.

I'm not convinced. At some point, you will have to debug something weird in your docs system.

If you deploy Hugo, that means understanding Go. Docusaurus--Javascript, Node, and that entire ecosystem. With this, it's Zig all the way down.

Zig users tend to be (possibly notoriously) anti-dependency.