> This is the place where people usually reach out for heavy artillery of [..] Nix, which solves the problem of “works on my machine” by turning your machine into mine!
This is ironic, because what they've done is just hand-roll their own mini Nix.
> Violation of our zero dependency principle: as Docusaurus is based on NodeJS, it added a lot of dependencies to our code base. We have a check that no large files are committed to git, and package-lock.json failed this check.
What is the purpose behind the second sentence? Or rather which?
- We want all source to be byte-sized and human-understandable
- We don't like how git/other tools work with large files?
If the latter, fine, but if it former, then I think you're violating the spirit, if not letter, by pinning a pre-built static binary of pandoc. The machine code is definitely not inspectable, and the build-time inputs closure (back to source files) is still massive, involving Lua and many bootstrapped GHCs for Haskell!
What makes Nix "heavy weight" is not some "take over your whole system" approach (on Linux, you can skip the installer and just run the Nix binary), but because tries to "cheat" with prebuilt binaries as little as possible.
HN readers, you can say what you want, but you gotta admit: TigerBeetle’s got style. And they do things differently and nicely.
In the current era where there are off the shelf tools that solve most problems its refreshing to see something like this. It would have been easy to embrace an existing open source or SaaS solution, but they understand that their docs are not a side part of their product but central to it, so they took ownership and built something to meet their needs.
Browsing through their docs, they are clean, beautiful, and indeed very fast. Hats off to the team that built this.
> methodology has a second order effect on motivation
Can't agree more.
I think a lot of development teams overlook this.
I'm a fan of "Tigerstyle" so far.
Although I find bits in Zig a questionable. The way zig build-tools links libc is quixotic and leads to fun link errors from other build toolchains. Not sure if that is the Zig developers adopting a similar mindset but it does make linking and packaging Zig code a touch more difficult (we ended up having to use `patchelf` to set the headers properly in order to avoid linking issues with Tigerbeetle's C client). Or the way Zig turns asserts into assumes in ReleaseFast builds which leaves in UB?
However the tigerbeetle codebase is pretty great, Tigerstyle definitely seems to be working.
Update: re, motivation: if it's a pain, nobody wants to do it, and rarely will. docs are important!
Docusaures isn't the best documentation tool out there, that's true. And of course building your own thing is nice, and it looks great. But wouldn't the better option be, to just use Starlight (my preference), Vitepress or Nextra?
Seeing Primeagen featured on homepage is concerning - a financial database requiring absolute reliability doesn't align with someone whose brand is built on chaos and controversy.
Lovely simple solution!
You should choose dependencies as carefully as you choose your partner.
I still haven't come across any doc which ever captured the beauty of memcached. That little story is seared into my brain.
[flagged]
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_.