15,004 karma · joined June 16, 2017
I'm writing a book to help developers improve their writing at https://refactoringenglish.com
All things being equal, why prefer Docker Compose? From my perspective, a single binary strictly dominates any Docker Compose solution.
Can you explain why my analogy is flawed?
> my critique is at somebody with a printer annoyed they can't get it to print its own instruction manual, so they've drafted one with a pen and are passing it around for feedback.
> Why aren't you using the printer?
You've lost me. Didn't you establish that the printer can't print its own instruction manual? How would I use the printer to print the instruction manual when it can't do that? And can you spell out for me how this relates to my critique of agents?
If this is about my gripe that agents have to search online for their docs, that's my most minor grievance because they can still access their docs. I just think it's a dumb time tradeoff that they don't ship docs alongside their binaries because if the docs were locally available, the agents could search them faster and guarantee the docs matched the binary.
> Feed your blog post to pi - have it implement it - and you will realize pretty quickly that a lot of them are flawed. This would have costs you about the same time as writing this blog post.
I never made the claim that Pi could implement these features trivially. If your claim is that Pi can do this so easily, you should be the one feeding my blog to Pi and showing me the results.
I'm confident that Pi could not implement all the features I described in the time I spent on this blog post (about five hours), so I have no reason to waste five hours trying, but if you're confident I'm wrong, you're welcome to spend your own five hours disproving me.
I'm confused about opencode's v1/v2 split. The docs say v2 is here, but their Github is only v1.x.[0] And the docs don't really explain why v2 is better, but there's a long list of things I have to do to migrate,[1] so I haven't been that eager to pull the trigger, especially since I can't tell if they consider it alpha/beta/release.
My take is that agents don't do the expected thing out of the box. I acknowledge that you can extend some agents and customize them, but I'm saying that it's sort of silly that the features I think most people want don't exist as default, out of the box standards.
> If I wrote a blog post complaining that "Programming languages don't let me do memory management", would you not think it's fair to respond with "What are you talking about? Have you heard of C?"
I don't think that's a fair comparison because C does let you do memory management out of the box. I think the better comparison is like, "Go doesn't let you do pattern matching," and the response is like, "Why don't you just patch Go to let you do pattern matching and maintain your own fork of Go?"
But I'm still kind of puzzled by this critique. Isn't it kind of like saying, "Why are you complaining about the agent? The C programming language exists, so you can use that to create any agent you want."
I don't expect the model to be trained on the latest features of the harness, but I think the harness should ship with its own docs so that the model can quickly search local docs rather than search online page by page for docs that don't necessarily match the local harness.
Looks like this is a layer on top of OpenCode. Seems interesting. I'll check it out. Thanks for the tip!
I'm confused how you see this article as a complaint about Pi. I only mention Pi at the very end to say it's one of the agents I've tried. I checked it out, found it too barebones for me and moved on, but I understand why some people prefer it. The existence of Pi isn't a counterargument to, "Why don't agents support development workflows that should be commonplace?"
I didn't want to complain about OpenCode too much because it's open-source and kind of the scrappy underdog to Claude/Codex, but I do find its multitasking support pretty limited. I have to specifically remind it to spin up subagents, and when it does, it'll do 2-3 tasks in parallel and then wait until all of them finish. It can't seem to inspect tasks in progress, and if a subagent dies or hangs, the main agent can't seem to retrieve any information from it, even though I as the human can look at the session and see what happened.
Are you doing anything special to make OpenCode multitask well?
But to take Spolsky's "Things You Should Never Do" as an example, obviously nobody's Googling, "things to never do," clicking Joel's article, and then getting annoyed at Joel for not telling them immediately. They're finding the post on HN, RSS readers, forums, etc., where they didn't have a specific goal in mind beyond learning/entertainment, so the author has more room to take their time.
I can understand the position that you do care about other people reading your post, but you weigh your own enjoyment of your posts more heavily than anything else, but I'm skeptical of the claim that you don't care who reads your posts.
> I think your anti-patterns apply very well to the stereotypical SWE or HN reader, and if that is who you are targeting, you should absolutely follow these. But the biggest anti-pattern of all is following these anti-patterns while hoping to appeal to the untypical SWE or HN reader.
Can you share more about what you have in mind?
I feel like these recommendations apply outside of software/HN. Like if I had a way to reach knitting bloggers, I'd imagine most of the concepts would be the same with different specifics.
Do you have a software blogger in mind that writes well but doesn't match what I describe in the post?
When bloggers say, "I don't want to write about topic X because person Y already wrote the definitive post about it," I say, "However good the existing article is, there will still be people that prefer yours." Even if the other person is smarter, more knowledgeable, whatever, you're going to explain it in your own way, and that's going to resonate with a distinct set of people than any other article out there.
If you click on a blog post, and the writing is poor or seems LLM-generated, you keep reading? Or do you mean that you're willing to forgive more superficial things like meandering or excessive formality if the post has other redeeming qualities?
As an example, I clicked a post a few weeks ago about orchestrating Claude Code sessions[1], as that's a topic I'm interested in, but I found the writing so poor that I felt like the post was either LLM-generated or written for someone who had different needs than I did. Would you read a post like that to completion if the topic interests you?
[0] https://lobste.rs/s/youq7y/how_write_blog_posts_developers_r...
This is something I see a lot too, and I almost covered it in the post. I think it goes hand in hand with excessive formality where people think that if you're writing a blog post about something, you have to be an authority on the topic, but that's not true.
It's valuable and useful to write about things when you're still a beginner as long as you present yourself as a beginner. Julia Evans does this extremely well. My favorite example is "Some notes on using nix,"[0] which got me to start using Nix when I'd seen lots of other posts from more experienced Nix users that were too in the weeds for me to understand. But the way Julia approaches it is that she's learned a little bit more than someone who's never touched it, so you can read her progress and get a slight head start from where you would have started without her notes.
[0] https://jvns.ca/blog/2023/02/28/some-notes-on-using-nix/
A lot of Paul Graham and Joel Spolsky posts don't get straight to the point and usually do not follow an intro -> body -> conclusion format. A lot of them start with a story that makes the direction of the post unclear[0] or include long digressions whose value isn't immediately obvious.[1]
For a while, I struggled with this contradiction because I think good writing should quickly demonstrate the value a reader can expect, but I think Graham and Spolsky are excellent writers that frequently take their time in getting to their point.
The easy answer is that Graham and Spolsky are famous, so they can do whatever they want, and people will still read. I've come to think it's actually that writers like Graham and Spolsky are so good that the quality of the writing itself is the thing of value that keeps you interested even if you don't know what point they're going to make.
[0] https://www.joelonsoftware.com/2000/04/06/things-you-should-...
Happy to take any feedback or questions about this post or hear your favorite software blogging anti-pattern.
It sounds like you're parodying the article but putting it in quotes is misleading.
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 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.
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...
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."
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."
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...