5 ms·
We Designed TigerBeetle's Docs from Scratch
- systemswizard 2y ago[flagged]
- bryanhogan 2y agoDocusaures 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?
- genericperson66 2y agoWhy do we live in a world where a simple docs site is considered too complex to roll your own and requires humongous frameworks?
- bryanhogan 2y agoBecause a "simple" docs site takes weeks or months of work that you could invest into other projects instead. What about Starlight or Vitepress is humongous? In this case the downsides don't outweigh the upsides, at least that was my first thought, hence I asked.
- jorangreef 2y agoExcept, this didn’t take longer. In fact, it would have taken longer had we had to “sculpt” the dependencies. But—we also wouldn’t have had the same quality. Again, I don’t mean to suggest that you should necessarily “paint” like we do at TigerBeetle, but we’re happy with the time and quality of the project, that it (more than) met our standard. We’re not trying to impose TigerStyle on you, but it works for us.
- genericperson66 2y agoGot you, I think the article made it clear that this solution did in fact not take months of work, as the heavy lifting is done by pandoc. The resulting solution is also very simple and can be understood completely in a short amount of time (very big upside). A framework based on node, typescript, npm etc. is by humongous by default.
- bognition 2y agoIn 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.
- jorangreef 2y agoThanks @bognition, appreciate the kind words!
- hakkotsu 2y agoSeeing 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.
- tpetry 2y agoAn interview with an influencer instead of e.g. a real customer is really a strange decision.
- jorangreef 2y agoWe could make it more clear, but it's not an interview. The link is to a video of a talk we presented about TigerBeetle, it's an overview and demo. If you haven't watched it yet, take a look and let me know if you still feel that we shouldn't point people to it. https://www.youtube.com/watch?v=sC1B3d9C_sI https://www.youtube.com/watch?v=sC1B3d9C_sI
- leosanchez 2y agoWhat controversy ?
- sfryxell 2y agobrand is doing the same work as personality in this sentence
- yobert 2y agoI think that's a bit disingenuous. How is his brand built on chaos and controversy? I've watched some of his videos and he honestly seems like a really reasonable guy.
- heavensteeth 2y ago"chaos and controversy" might be a stretch but I see him solely as an 'influencer' rather than a programmer. Clickbait, reaction content; I remember the last video I watched of his was a C "code review", but based on what I watched, he doesn't know C. Lots of uninformed opinions appealing to people who don't really know what they're seeing.
- mtlynch 2y agoI 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/92c991cfe48652feee491d4f46527b80 https://gist.github.com/mtlynch/92c991cfe48652feee491d4f4652... Edit2: Nevermind, they actually do but in HTML. Hat tip to pfg_.
- agentultra 2y ago> 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!
- Ericson2314 2y ago> 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.
- matklad 2y agoThe second one. `git clone` only gets slower with time, so it's important to optimize for it.
- genericperson66 2y agoLovely simple solution! You should choose dependencies as carefully as you choose your partner.
- mahithefish 2y agoHN readers, you can say what you want, but you gotta admit: TigerBeetle’s got style. And they do things differently and nicely.
- ilrwbwrkhv 2y agoI still haven't come across any doc which ever captured the beauty of memcached. That little story is seared into my brain.