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_.

Joran from TigerBeetle here!

We didn't design our docs because it was "a fun thing" (as suggested) but rather because we simply care deeply about the experience of developers reading our docs. For example, concerning performance and offline use, which were further reasons we gave in the post.

We have a high bar for taking on dependencies. We don't take on dependencies automatically without justification. It's just not a philosophy that we share, to assume or to insist that everything needs to be a dependency.

(The discussion on CSP in our post was also not given as motivation, but as an example of the thought process that went into this. Again, as per the post, it's a matter of defense-in-depth. We have plans for how our docs will be used in future, that you may not be aware of, and security is important.)

Finally, we're happy with the result, the project was small and didn't take long. We're used to "painting" things like this fairly quickly. It's just easier for us than trying to "sculpt" off the shelf dependencies. That's not to suggest that everyone needs to paint like we do at TigerBeetle, but it's equally true that not everyone needs to sculpt either. [1]

[1] To understand our engineering methodology, and why we prefer to paint than sculpt, see TigerStyle: https://www.youtube.com/watch?v=w3WYdYyjek4

Hi Joran, thanks for your response!

For context, I like TigerBeetle, and I respect the team. I'm not trying to take cheap shots but rather to disagree respectfully.

>We didn't design our docs because it was "a fun thing" (as suggested) but rather because we simply care deeply about the experience of developers reading our docs. For example, concerning performance and offline use, which were further reasons we gave in the post.

To me, this still sounds like "for fun."

The blog post just talks about performance and offline use, but "maximize performance" isn't a real goal. You can invest ininite hours improving performance, so it comes down to how many engineering hours you're willing to trade in exchange for improving some set of performance metrics.

Maybe the issue is that the blog post doesn't present the decision making process well? Because the critical questions I don't see addressed are:

- What were the performance metrics that were critical to achieve?

- What alternative solutions were considered beyond Docusaurus?

- How do the alternatives perform on the critical metrics?

- How does the home-rolled solution perform on TigerBeetle's critical metrics?

In the absence of those considerations, it feels like the dominant factor is that it's more pleasant to work with greenfield, home-baked code than off-the-shelf code, even if the existing code could achieve the same thing in fewer engineering hours.

To be clear, we have fun at TigerBeetle!

And to be fair, we did present the metrics (footprint etc.), and we did discuss alternatives to Docusaurus (e.g. Zine, which is pretty great!).

I think at the heart of your argument is this assumption that unquestionably taking on dependencies would achieve the same quality in less time, and that a methodology such as TigerStyle that challenges this assumption need necessarily take "infinite time". You almost force us to apologize that we don't share this view! :)

But again, this was the quickest, highest quality path (for us, at least!).

Have you read TigerStyle, our engineering methodology? And have you watched our talk? Perhaps that will help close the gap in understanding how we think about engineering at TigerBeetle: not as an expense to be minimized, to minimize only our own development time, but as an asset, to be invested in, since we build it once, but developers enjoy it many times over. However, as you watch TigerStyle, you'll see it's not only about quality, but also a way to get quality in less time (go slow to go fast).

In other words, I think we differ when it comes to Total Cost of Ownership. We're not trying to minimize only our own development time, but investing in it, to produce something quality for our community, and so minimize the Total Cost of Ownership across the relationship as a whole (ours + community) [1].

[1] Our talk on our business methodology, Biodigital Jazz! goes into this idea of TCO across the community: https://www.youtube.com/watch?v=C98cyJ-wJuY