mtlynch

Good in terms of prompt communication and fix. Absurdly bad in terms of reward.

Earlier in the article, it mentions that Baseten is valued at $13B. They can't dig into their couch cushions to give a few thousand dollars to the researcher privately disclosing a bug that let an attacker escalate to admin in their GitHub org?

This sends the message that honest researchers should not waste their time looking for vulnerabilities in Baseten, but it's a good target for criminals who want to monetize these vulnerabilities.

> I do agree with you put I would push a little further - is it that complexity itself is the enemy? Or is it that the secondary outcomes of complexity (bugs, more effort to make changes, confusing code) are the enemy?

I agree, but I think we're still a long way away from being able to trust AI to manage all software complexity for us. For one, LLMs frequently get tripped up by their own complexity. But even if the complexity didn't make LLMs more error prone or expensive to run, you still often need a human in the loop to understand what the system does.

I think of it kind of like compilers. Compilers do a good enough job that 99% of developers don't understand code at the bytecode or machine instruction level, but if we lost that last 1% of programmers who understand CPU instructions, we'd be in serious trouble.

It's hard to say without knowing what things are like at the company/team you work for, but I can say the things you're describing sound unusual to me.

Most significantly, it's strange for the person writing the design doc not to be the person implementing the code. This is asking for trouble because there's a principal-agent problem[0], and also there's bound to be signal lost in the handoff between designer and implementer. It's not so unusual for the design doc author to work with a team on implementation, but they'd still be actively involved in implementation, which sounds different from what you're describing.

I've also never heard of this separation between a conceptual design doc and a logical design doc. I've been on teams where the product manager writes a UX-focused spec, and then the dev writes a technical-focused spec, but I've never heard of a conceptual vs. logical spec.

Does the org have a strong engineering culture in other ways? Like automated tests, automated deploys, automated monitoring/alerting, useful code reviews? Because the easiest answer is that you're in an org with poor software engineering practices, or at least weak documentation culture, and the design review process you're experiencing is there for historical or political reasons rather than engineering reasons.

[0] https://en.wikipedia.org/wiki/Principal%E2%80%93agent_proble...

I find that LLMs are still worse than humans at limiting complexity, which is one of the most important outcomes of a design review.

If I tell a senior SWE that I'm creating a Discourse-like discussion forum, and I want users to have three options for selecting an avatar: (1) import from Gravatar, (2) upload a JPG or SVG or PNG or GIF, or (3) let the user draw their avatar on a canvas, the LLM will happily go and design that and write a 5 KLOC implementation, whereas a good SWE would push back and say, "That's like 10x the complexity of just allowing JPGs. How about we simplify it to say that in v1, the only option is to upload a JPG."

I've tried working with Fable/Sol and saying, "Look for features that we can simplify to reduce complexity," and they don't understand. They'll guess at features we can cut entirely, but they fail to see how to capture the essence of the feature without the complexity.

I've noticed this a lot with Fable recently. Like I'll say, "Show an error message in the web UI if X fails," and Fable comes back with this like 800 LOC error message generator that has switch-cases and combines inputs from three different sources when all I wanted was something like, "Update failed: database is locked."

Thanks for reading!

What you're describing sounds like toxic team dynamics rather than something specific to design docs. Do you work effectively with your teammates outside of design docs, or is there similar tension/hostility everywhere?

What you're describing sounds like the design process working as intended (modulo the finger-pointing). The design doc should be unambiguous, and the implementation should match it.

Assuming this isn't just symptoms of a sick team, my other explanation is that your teammates find your deviations from the design doc unexpected. It sounds like you're running into situations where you can't implement the design doc as written, so you're proactively making your own design choices and showing your teammates the implementation. Could you loop your teammates in earlier on before you've implemented the code? Like, "The design docs says we're supposed to use SQLite, but I realized that SQLite doesn't support types the way we expected, so I think we should switch to Postgres for X, Y, and Z reasons."

I answered this in another comment,[0] and I don't think there's widespread agreement on this, but I think design docs should be a short-term doc that lives until the design implementation is complete. I don't think design docs are the right format for a document that has to evolve alongside the code forever.

[0] https://news.ycombinator.com/item?id=49698580

Fun piece of trivia, Joel published one of his functional specs.[0]

As a huge fan of Joel's writing and engineering ideas, I was actually underwhelmed by his spec. It wasn't bad but it also felt like he missed a lot of opportunities to articulate design decisions to the reader more quickly or clearly.

One obvious mistake is that there's over a page (in a 20-page spec) just dedicated to coding conventions and what prefixes variable names will have. I think Joel later conceded that it was a mistake to cover naming conventions in a spec, though I can't find a link now.

[0] https://web.archive.org/web/20051028171624/https://www.joelo...

> The biggest thing AI enables is cheap code.

Agree, but in my experience that doesn't change much about the design doc.

I think it's helpful to the author to be able to say to an AI agent, "Hey, put together this quick prototype," and that informs the design doc. But if the goal is to review the design decisions with the team, I don't see how you get around the design doc. I don't want a teammate to send me 10 KLOC of AI-generated code and ask me to review the design. Even if you told AI to try 10 different ideas and pick the best, I don't trust AI to make the same decisions as my human teammates.

Thanks for reading!

This is a good question, and I have a super long answer that's been in my head for like 8 years about how to influence your teammates to adopt good engineering practices.

The short answer is that most useful software engineering practices are a risk to the first person on the team to adopt them. For example, if everyone on your team thinks automated testing is stupid and you adopt automated testing, it will look like your work is worse because you're slower in the short-term, and maybe you have to do even more work when teammates break your tests.

It comes down to accruing social currency with your team. Your teammates don't want to take a risk for you if you have a history of bad ideas that wasted everyone's time. But if, for example, you implemented automated deploys to replace a tedious workflow developers had to do manually, people would see how your ideas have payoff, and they're more willing to invest a little bit if they expect ROI long-term.

When I've convinced my teammates to invest in design docs, I made sure I had some wins under my belt before I started pushing for everyone to write design docs. I invested a lot in docs myself so my teammates could see the value before I asked them to start writing.

This is also a place where you have to think about politics a bit. Documentation has a much better shot if it has support from the top, so think about the pitch to your manager or dev lead about how design docs make their jobs easier.

Yeah, this is difficult.

My rule of thumb is to ask myself, "Is there a chance my reviewers would not have signed off had this been in the design doc they reviewed?" If the answer is yes, I send it out for a follow-up and explain why I had to change the design.

In my experience, the response from my reviewers is generally, "Yeah, that's fine." It's a combination of (1) the practical limitations that it's hard for them to get the whole design back into mental context to argue about it and (2) they trust that I'm taking the design seriously and have thought this through. I think occasionally, I've sent a post-approval change out and someone points out something

It's common to encounter a curveball nobody anticipated at design time, but if you just go rogue and unilaterally make design decisions, it degrades trust and undermines the review process, so I want my reviewers to know that I'm taking their feedback seriously.

> I think in the age of AI coding, these rationales are a bit outdated. And if you think they're not - I'm curious to know why you think so.

Can you share more about how you think AI invalidates these rationales?

Thanks for reading!

> Isn't much of this made redundant by being part of an existing system?

I haven't found that to be true in my work. If you're only making a minor change to an existing system, then you may not need a design doc, but a significant change to an existing system has as much, if not more, complexity and ambiguity than greenfield development.

> Also, this level of detail is a recipe for being outdated once the issues, compromises and compromises starts coming in

I think this is what people typically get wrong about design docs.

I don't think design docs are a good medium for being the perpetual, living description of the system. I think design docs should capture the design at the time of implementation. You should modify the design docs while you implement the work called for in the design document, but once you're done with that work, you freeze the document and preserve it for posterity only.

The design doc is about a specific change to the system. If you need a doc to describe the high-level architecture of the system as it evolves, that should be a different doc.

OP here!

I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons:

1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, reinforcing everyone's belief that they're a pointless ritual.

2. The developer does not like other people questioning their engineering choices, and they know that it's harder for their teammates to push back on finished code than a design doc. Investing in the implementation before design changes the calculus to bias in favor of whatever's already implemented rather than what would have been the ideal implementation. Plus, it's harder for the team to review design decisions of 10k LOC than a 5-page design doc.

OP here.

Thanks for reading and for the thoughtful feedback!

> Only real criticism I have here, is I would not include any code in a design doc, unless it is really really vitally important.;

Yeah, that's fair. If I were setting guidelines for a large org, I'd maybe discourage code snippets in design docs, as it's hard to know when is too much. At my last company, the dev team was just 3-4 people, and I found it helpful to have little snippets in design docs especially when we're talking about semantics of a new library or how to migrate existing code to a new system.

> Orthogonal to the article, but this line of thinking (including the link to the classic 2000 "Things You Should Never Do, Part I" article[0]) may be worth reviewing in the post-LLM world; for all their flaws, LLMs are spectacular at language-to-language translation, and we already have one major project released[1] that shows porting a relatively large and mature project from one language to another is possible.

Yeah, I agree this could change with LLMs, but I think Joel is still correct up to today. Bun is an interesting case because it's friendliest possible conditions for an LLM rewrite (self-contained inputs and outputs, easy to test old implementation and new implementation side by side, huge test corpus w/ third-party tests). I haven't followed it closely, but it seems like the jury's still kind of out as to whether the rewrite was a good idea.

Author here. Happy to take any feedback about this post.

I learned to write design docs at Microsoft and Google, and I thought they both had good culture around docs that hasn't percolated out as well as other engineering practices at those orgs. I haven't seen a thorough explanation of how to write design docs, so this is my attempt to externalize what I've learned about writing them.

I haven't seen Greg's stuff before, but I discovered Disco through this, and it looks neat:

https://disco.cloud/

> Binding arbitration on individuals should be illegal, full stop. The only use case is taking away people's rights as consumers and workers. Or dodging responsibility for deadly mistakes like the Disney+ incident.

Hijacking to link to another website that has good information about how binding arbitration is stacked against the consumer/employee:

https://arbitrationinformation.org/

I love this idea and hope to see more on-device models. How do they make money, though?

I tried out their demo for Clear, the audio quality improvement model.[0] I'm not sure if it's just I don't have refined enough an ear or their demo is broken, but the "raw" and "enhanced" versions sounded exactly the same to me.

[0] https://desertant.com/models/clear/

> That's a lie. 9€ is not the max you pay, it's metered and extra traffic costs extra. So what you said about others can just as well apply here.

From the pricing FAQ[0]:

> Can I set a spending limit for overages?

> Yes. Please contact support in order to set up your spending limit.

None of the others support spending limits last I checked.

[0] https://www.statichost.eu/pricing/

Which vendor are you talking about?

As I mentioned upthread, statichost.eu uses Bunny under the covers, and I think you'd be hard-pressed to argue that Bunny isn't a CDN.

surge.sh has servers in 10 regions.[0]

It's not trivial to run a static host with redundancy in multiple regions, but it's also not so absurdly complex that only large vendors can achieve it.

[0] https://surge.sh/network

> Can I just point out that either the vendor is small and therefor can’t actually offer the N+2 reliability you list as a weakness of self-hosting, or they are large enough for N+2 but then stop being small.

I don't understand what you mean. surge.sh and statichost.eu are both small vendors that offer redundancy. Are you saying they're not really small or not really offering N+2 reliability?

I've seriously considered it, but then the VPS is my single point of failure. If there's a new nginx/apache/caddy/linux 0day that could compromise my server, I have to care about it and update.

My websites typically serve 500 GB to 800 TB of bandwidth per month, and I run my businesses on static sites. It's not often that I get a big burst of visitors, but it happens a few times a year, and I wouldn't want to lose out on hundreds to thousands of dollars in sales because I was trying to save $20/mo on hosting.

What's the price that you expect to pay to a service run by a single person that has to keep your website available 24/7?

I get frustrated that people seem pretty aware of the enshittification and centralization of large services, but when an indie vendor pops up that can fill a niche, people expect it to have all the bells and whistles of a billion dollar company and also give everything away for free.

If you have a just for fun website, then yeah, hop around the free tiers of whatever hosting service. If you're running any kind of online business, the difference between free and 9€/month for web hosting is a rounding error to pretty much any other business expenses you have.

Also, keep in mind that on the 9€/month plan, that's the max you pay. With Vercel, Netlify, Firebase, etc., if you get hit with a bot attack, they come after you for $100k+ and you have to beg on social media for them to call off the collectors.[0]

[0] https://old.reddit.com/r/webdev/comments/1b14bty/netlify_jus...

> An EU tiny VPS on Scaleway with unlimited bandwidth costs 5€. This thing costs 9€. With limited bandwidth.

statichost.eu is a CDN,[0] not a single static host. Your VPS is the single point of failure, so if that one system goes down, your site is offline.

With a VPS, you'd also have to roll your own atomic updates, which is not the hardest thing in the world, but it's also not trivial.

Compare it to static hosting pricing at Netlify, Firebase Hosting, and Vercel, and it's competitive, but you should expect to pay more for a service run by a small vendor who doesn't have the economies of scale or VC money that the bigger competitors have.

[0] They're an abstraction on top of Bunny, who provides the actual CDN, statichost assumes responsibility for providing the CDN regardless of underlying infrastructure.

I've been looking for a new static host recently since Netlify raised prices and is terrible at preventing bot traffic. Here was my assessment of Netlify from the perspective of a small customer who just wants static hosting (and not build minutes).

Pros:

- Run by a single person, so customer service is responsive and comprehensive

- Focused mainly on static hosting without extra complexity

Cons:

- Run by a single person, so increased outage risks

- No support for MFA

- The upload process unconditionally uploads every file rather than an rsync-like sync of only the changed files, which is a pain for my large sites that only change incrementally

- Bot scraper protection is not included (they'll do it for an additional fee)

- Bundles together site builds and hosting, but I only want hosting

Isn't ERSC aiming to be for jj what GitHub was for git? In which case, this would be great news for jj.

I like the idea of Monica and having a way to remember things about friends and acquaintances. I tried using Monica self-hosted for about a year and felt like the authors of Monica had totally different priorities from me. This post captures it well:

> Relationships are a good example. Storing that Monica is Ross's sister doesn't seem particularly complicated. But if Monica is Ross's sister, Ross is also Monica's brother. A parent relationship implies a child relationship. Some relationships have a direction while others don't. Real families include divorces, remarriages, stepchildren, half-siblings, adoption and all sorts of structures that don't fit nicely into a predefined list. Different cultures also describe family relationships differently.

My opinion: this stuff doesn't matter at all and is not useful for Monica to try to capture or model.

If I meet someone at a conference or have a phone call with a long distance friend, I want to remember what we talked about. If they mention that they're planning a vacation to Thailand, the next time I talk to them, I want to say, "How was your vacation to Thailand?" I don't need software to graph all of the people in their family or to pick out "met this person at a conference" from a dropdown of 1000 options. I definitely don't need software to natively represent that two people have a half-sibling relationship as opposed to full siblings.

I switched to just plain markdown files, and I never missed the relationship modeling feature of Monica, but I would like a tool that does things plaintext can't like remind me to reach out to someone I haven't spoken to in a while or remind me to follow up with someone (e.g., they're interviewing for the next few weeks so check in next month to see how that's going).

Worth noting that TrueNAS recently stopped publishing their build scripts, intentionally making it harder to build their open source code.[0]

[0] https://forums.truenas.com/t/clearing-the-air-on-build-scrip...

I couldn't understand what this article was saying.

There's nothing nefarious about EDIDs. EDIDs are just a way of the monitor to announce its capabilities to the device so that the device and the display can agree on things like resolution, refresh rate, etc. EDIDs are just blobs of data without capability to execute logic, as far as I'm aware.

It sounds like the author is claiming that Windows does some sort of driver update in response to EDID announcements, but OP doesn't explain it at all. If that's true, that would entirely be on the Windows end not on the EDID's end. It sounds like Windows is recognizing LG as the manufacturer declared in the EDID and then downloading a driver for LG. I don't think there's any way for the EDID to declare to the OS that it wants to perform a driver update.

> So, what am I missing?

Gerrit/CodeApprove/Reviewable-style reviews are actually designed for exactly the scenario you're describing.

The thing you're missing is that it's helpful to see a diff view of, "What changed since my last review?"

If your review workflow is:

1. Junior engineer makes 15 commits to implement a feature in 300 LOC

2. Junior engineer sends you the PR for review

3. You review and send your notes to the engineer

4. Junior engineer makes 15 more commits and another 100 LOC churn, but PR is 350 LOC total diffs

At (4), the thing you probably want to see are the 100 LOC of diffs since step (3). I haven't tried this on GitHub for awhile, but last I checked, your options are to either view only diff of PR against main branch, view each of the 15 commits individually, or hand edit the URL to get the "what's changed since (3)?" view.

On Gerrit/CodeApprove/Reviewable, they all default to "what changed since I last reviewed?" and you comment on that diff rather than what's changed against the main branch, which is the default on GitHub.