Forwarded from HN Best Comments
Re: How I, a beginner developer, read the tutorial you, a developer, wrote for me
Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
nomilk, 16 hours ago
Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
nomilk, 16 hours ago
❤2
Forwarded from HN Best Comments
Re: AI was supposed to help juniors shine. Why does it mostly make seniors stronger?
The best code I've written with an LLM has been where I architect it, I guide the LLM through the scaffolding and initial proofs of different components, and then I guide it through adding features. Along the way it makes mistakes and I guide it through fixing them. Then when it is slow, I profile and guide it through optimizations.
So in the end, it's code that I know very, very well. I could have written it but it would have taken me about 3x longer when all is said and done. Maybe longer. There are usually parts that have difficult functions but the inputs and outputs of those functions are testable so it doesn't matter so much that you know every detail of the implementation, as long as it is validated.
This is just not junior stuff.
bentt, 4 days ago
The best code I've written with an LLM has been where I architect it, I guide the LLM through the scaffolding and initial proofs of different components, and then I guide it through adding features. Along the way it makes mistakes and I guide it through fixing them. Then when it is slow, I profile and guide it through optimizations.
So in the end, it's code that I know very, very well. I could have written it but it would have taken me about 3x longer when all is said and done. Maybe longer. There are usually parts that have difficult functions but the inputs and outputs of those functions are testable so it doesn't matter so much that you know every detail of the implementation, as long as it is validated.
This is just not junior stuff.
bentt, 4 days ago
👍1
Forwarded from HN Best Comments
Re: Claude Skills are awesome, maybe a bigger deal than MCP
We're doing something like this internally. Our monorepo context files were much too big, so we built a progressive tree of fragments to load up for different tasks.
I am struck by how much these kinds of context documents resemble normal developer documentation, but actually useful and task-oriented. What was the barrier to creating these documents before?
Three theories on why this is so different:
1) The feedback loop was too long. If you wrote some docs, you might never learn if they were any good. If you did, it might be years later. And if you changed them, doing an A/B test was impractical. Now, you can write up a context markdown, ask Claude to do something, and iterate in minutes.
2) The tools can help build them. Building good docs was always hard. Especially if you take the time to include examples, urls, etc. that make the documentation truly useful. These tools reduce this cost.
3) Many programmers are egotists. Documentation that helps other people doesn't generate internal motivation. But documentation that allows you to better harness a computer minion to your will is attractive.
Any other theories?
michael1999, 20 hours ago
We're doing something like this internally. Our monorepo context files were much too big, so we built a progressive tree of fragments to load up for different tasks.
I am struck by how much these kinds of context documents resemble normal developer documentation, but actually useful and task-oriented. What was the barrier to creating these documents before?
Three theories on why this is so different:
1) The feedback loop was too long. If you wrote some docs, you might never learn if they were any good. If you did, it might be years later. And if you changed them, doing an A/B test was impractical. Now, you can write up a context markdown, ask Claude to do something, and iterate in minutes.
2) The tools can help build them. Building good docs was always hard. Especially if you take the time to include examples, urls, etc. that make the documentation truly useful. These tools reduce this cost.
3) Many programmers are egotists. Documentation that helps other people doesn't generate internal motivation. But documentation that allows you to better harness a computer minion to your will is attractive.
Any other theories?
michael1999, 20 hours ago
❤1
Forwarded from HN Best Comments
Re: Replacement.ai
Personal belief, but robots coming for your jobs is not a valid argument against robots. If robots can do a job better and/or faster, they should be the ones doing the jobs. Specialization is how we got to the future.
So the problem isn't robots, it's the structure of how we humans rely on jobs for income. I don't necessarily feel like it's the AI company's problem to fix either.
This is what government is for, and not to stifle innovation by banning AI but by preparing society to move forward.
TechSquidTV, 2 hours ago
Personal belief, but robots coming for your jobs is not a valid argument against robots. If robots can do a job better and/or faster, they should be the ones doing the jobs. Specialization is how we got to the future.
So the problem isn't robots, it's the structure of how we humans rely on jobs for income. I don't necessarily feel like it's the AI company's problem to fix either.
This is what government is for, and not to stifle innovation by banning AI but by preparing society to move forward.
TechSquidTV, 2 hours ago
Forwarded from HN Best Comments
Re: Replacement.ai
Personal belief, but robots are coming to have sex with your wife is not a valid argument against robots. If robots can do your wife better and/or faster, they should be the ones doing the job. Specialization is how we get to the future.
So the problem isn't robots, it's the structure of how your wife relies on you for lovemaking. I don't feel like it's necessarily the AI company's problem to fix either.
This is what government is for, and not to stifle innovation by banning hot robot sex with your wife, but preparing your family for robot/wife lovemaking.
everdrive, 2 hours ago
Personal belief, but robots are coming to have sex with your wife is not a valid argument against robots. If robots can do your wife better and/or faster, they should be the ones doing the job. Specialization is how we get to the future.
So the problem isn't robots, it's the structure of how your wife relies on you for lovemaking. I don't feel like it's necessarily the AI company's problem to fix either.
This is what government is for, and not to stifle innovation by banning hot robot sex with your wife, but preparing your family for robot/wife lovemaking.
everdrive, 2 hours ago
🌚4😁1
Forwarded from HN Best Comments
Re: When a stadium adds AI to everything, it's worse experience for everyone
I was recently at an events center, that has replaced all of their vending machines with machines that require me to install an app(!) to purchase a product. Literally, didn't take cash or credit - just via app.
Per the marketing on the side, this is meant to be for my benefit in order to earn "points" and get offered "deals." I don't think I have to tell you that I did NOT install the app, and just walked further to buy one from a vendor.
There is a massive arrogance problem within tech. Everyone thinks their product should be the center of everyone else's universe. The best products are invisible/get out of the way.
Someone1234, 11 hours ago
I was recently at an events center, that has replaced all of their vending machines with machines that require me to install an app(!) to purchase a product. Literally, didn't take cash or credit - just via app.
Per the marketing on the side, this is meant to be for my benefit in order to earn "points" and get offered "deals." I don't think I have to tell you that I did NOT install the app, and just walked further to buy one from a vendor.
There is a massive arrogance problem within tech. Everyone thinks their product should be the center of everyone else's universe. The best products are invisible/get out of the way.
Someone1234, 11 hours ago
👍3
Forwarded from HN Best Comments
Re: The Programmer Identity Crisis
To me, the most salient point was this:
> Code reviewing coworkers are rapidly losing their minds as they come to the crushing realization that they are now the first layer of quality control instead of one of the last. Asked to review; forced to pick apart. Calling out freshly added functions that are never called, hallucinated library additions, and obvious runtime or compilation errors. All while the author—who clearly only skimmed their “own” code—is taking no responsibility, going “whoopsie, Claude wrote that. Silly AI, ha-ha.”
LLMs have made Brandolini's law ("The amount of energy needed to refute bullshit is an order of magnitude larger than to produce it") perhaps understated. When an inexperienced or just inexpert developer can generate thousands of lines of code in minutes, the responsibility for keeping a system correct & sane gets offloaded to the reviewers who still know how to reason with human intelligence.
As a litmus test, look at a PR's added/removed LoC delta. LLM-written ones are almost entirely additive, whereas good senior engineers often remove as much code as they add.
strix_varius, 5 hours ago
To me, the most salient point was this:
> Code reviewing coworkers are rapidly losing their minds as they come to the crushing realization that they are now the first layer of quality control instead of one of the last. Asked to review; forced to pick apart. Calling out freshly added functions that are never called, hallucinated library additions, and obvious runtime or compilation errors. All while the author—who clearly only skimmed their “own” code—is taking no responsibility, going “whoopsie, Claude wrote that. Silly AI, ha-ha.”
LLMs have made Brandolini's law ("The amount of energy needed to refute bullshit is an order of magnitude larger than to produce it") perhaps understated. When an inexperienced or just inexpert developer can generate thousands of lines of code in minutes, the responsibility for keeping a system correct & sane gets offloaded to the reviewers who still know how to reason with human intelligence.
As a litmus test, look at a PR's added/removed LoC delta. LLM-written ones are almost entirely additive, whereas good senior engineers often remove as much code as they add.
strix_varius, 5 hours ago
💯3
Սա այս ալիքում հայերեն լեզվով առաջին գրառումն է։ Շնորհակալություն ուշադրության համար։
Forwarded from HN Best Comments
Re: The 'Toy Story' You Remember
This topic is fascinating to me. The Toy Story film workflow is a perfect illustration of intentional compensation: artists pushed greens in the digital master because 35 mm film would darken and desaturate them. The aim was never neon greens on screen, it was colour calibration for a later step. Only later, when digital masters were reused without the film stage, did those compensating choices start to look like creative ones.
I run into this same failure mode often. We introduce purposeful scaffolding in the workflow that isn’t meant to stand alone, but exists solely to ensure the final output behaves as intended. Months later, someone is pitching how we should “lean into the bold saturated greens,” not realising the topic only exists because we specifically wanted neutral greens in the final output. The scaffold becomes the building.
In our work this kind of nuance isn’t optional, it is the project. If we lose track of which decisions are compensations and which are targets, outcomes drift badly and quietly, and everything built after is optimised for the wrong goal.
I’d genuinely value advice on preventing this. Is there a good name or framework for this pattern? Something concise that distinguishes a process artefact from product intent, and helps teams course-correct early without sounding like a semantics debate?
janeway, 5 hours ago
This topic is fascinating to me. The Toy Story film workflow is a perfect illustration of intentional compensation: artists pushed greens in the digital master because 35 mm film would darken and desaturate them. The aim was never neon greens on screen, it was colour calibration for a later step. Only later, when digital masters were reused without the film stage, did those compensating choices start to look like creative ones.
I run into this same failure mode often. We introduce purposeful scaffolding in the workflow that isn’t meant to stand alone, but exists solely to ensure the final output behaves as intended. Months later, someone is pitching how we should “lean into the bold saturated greens,” not realising the topic only exists because we specifically wanted neutral greens in the final output. The scaffold becomes the building.
In our work this kind of nuance isn’t optional, it is the project. If we lose track of which decisions are compensations and which are targets, outcomes drift badly and quietly, and everything built after is optimised for the wrong goal.
I’d genuinely value advice on preventing this. Is there a good name or framework for this pattern? Something concise that distinguishes a process artefact from product intent, and helps teams course-correct early without sounding like a semantics debate?
janeway, 5 hours ago
Forwarded from HN Best Comments
Re: X's new country-of-origin feature reveals many 'US' accounts to be foreign-run
Reminds me of when Reddit posted their year end roundup https://web.archive.org/web/20140409152507/https://www.reddit... and revealed their “most addicted city” to be the home of Eglin Air Force Base, host of a lot of military cyber operations. They edited the article shortly afterward to remove this inconvenient statistic
ro_bit, 37 minutes ago
Reminds me of when Reddit posted their year end roundup https://web.archive.org/web/20140409152507/https://www.reddit... and revealed their “most addicted city” to be the home of Eglin Air Force Base, host of a lot of military cyber operations. They edited the article shortly afterward to remove this inconvenient statistic
ro_bit, 37 minutes ago
Forwarded from HN Best Comments
Re: Your job is to deliver code you have proven to work
> there’s one depressing anecdote that I keep on seeing: the junior engineer, empowered by some class of LLM tool, who deposits giant, untested PRs on their coworkers—or open source maintainers—and expects the “code review” process to handle the rest.
It's even worse than that: non-junior devs are doing it
as well.
endorphine, 3 hours ago
> there’s one depressing anecdote that I keep on seeing: the junior engineer, empowered by some class of LLM tool, who deposits giant, untested PRs on their coworkers—or open source maintainers—and expects the “code review” process to handle the rest.
It's even worse than that: non-junior devs are doing it
as well.
endorphine, 3 hours ago