Hacker News Reader

Comment by adastra22 | Hacker News Reader

I would throw the entire docs out and write it from scratch in your own words. I get that we live in an era where the machine writes most/all of the code, and I can accept that. What I need, to even consider using and extending this project, is some understanding of what part of the design is yours and what part is accident by Claude. I can't get that from reading Claudese.

View on HN

>>I get that we live in an era where the machine writes most/all of the code

Only on the Internet is this true, not in real life. I cannot and do not trust any of these things to do a proper job because they have not in any situation succeeded in any job I've given them. And no company I deal with claims otherwise

That's like me with violins!

Maybe violins don't write good code after all?

I can see that you only work with true scotsmen, but the machine really does write most of the code now, at least from a pure numbers perspective.

Right I feel like they just got to a point where they can reliably write individual functions with direction. Every time I've tried to use them consistently I feel like I just end up spinning wheels from them doing things that mostly work until it crashes and burns or just has straight up missing things or half truths. Skill issue or not it doesn't work for me.

Still glad I basically never have to debug a build issue or memory error again though

it's definitely true in real life. i think there is actually a massive skill gap in using them effectively.

If the Code is bad, you can tell it to fix it to match your expectations —only at the edges, are you going to have to spell it out.

Lack of documentation used to be a running joke.

The goose_spec.txt in 2019 would be "goose is like c and rust only with syntax like array{;}[] btw it uses a small amount of stacks instead of malloc."0 10klocs.

Now, we make sure the AI leaves documentation so it can figure out what it was doing earlier.

A local model a few generations and many weights behind newest Claude can implement my novel algorithms and write the documentation I wouldn't.

Yes, many times it does dumb CS for kindergarten mistakes but it only has to work towards the optimum every once in a while.

Sadly there seems to be no point in arguing online though.

- You need to have a mental model to grow an idea

- When a pattern is known you can use a library!

- When a pattern is not known AI will make stuff up

No matter how "good" coding with an AI will become there is no way you get around learning, having someone understand what's going on and take responsibility.

I'm fine with formal checking and fuzzing or getting hints where a bug might come from - but these are iterations on tools we used before like a debugger, strict types, functional programming and well fuzzing.

I tried to have an AI iterate on a step i don't fully understand yet and i always regretted it. Highly interconnected projects will grind to a halt until you do learn.

You can check with people doing highly specced software in the medical domain that even with very good specs there is ambiguity in natural language thus it can never be the source of reliable and manageable software.

However - i read about some smart guys in the 40s or so encountering the need for a formal language to tell a computer what to do with 0 ambiguity and i think they called it a "programming language"

> I tried to have an AI iterate on a step i don't fully understand yet and i always regretted it.

I had to accept this one too even for pretty simple things. I had an LLM wire up a neovim connection handler for me without bothering to read the libraries docs or neovims RPC spec and I completely regretted it. You would thing such a small piece would be fine but I couldn't work on it and had to rip it out and rewrite it, and reading the AIs reference code actually got me more confused than anything.

I've found the sweet spot for me is just writing code and promoting an AI whenever I have a question or if I'm not sure the code will do what I think. When I hit a point and I groan about doing something, if it's small and I understand what needs to happen already I will ask the LLM I've been prompting already to do it. Usually by that point it's already gotten enough context from the back and forth on my questions or me explaining assumptions it got wrong when reviewing my code.

A bit late to this thread but I couldnt agree more with this!

Personally, I love using AI! It speeds up my development a lot and over the past year, it's got incredibly good at writing code. It's still not comparable to what I'd manually do though, but i can make it work.

The big caveat is, it doesnt know what's good or bad; it doesn't know what's appropriate or not; it has no opinion or experience. If I'm building a system, I have to design it and try to understand what the reqs are and convert that into a code spec. Programming languages are great because the process of translating those natural language thoughts and ideas constantly hits edge cases that force a person to rework their spec and re-assess their decisions and assumptions. That is what engineering is.

Ai just make some stuff up when what you told it was unclear or ambiguous due to the natural language used as input. You can't just offload that thought process to AI because, quite frankly, most of the time, you dont have a very well defined, formal idea of what you want. It's therefore hilarious to hear vibe coders go: "oh i just prompted it to make a game for me!".

The tools have a learning curve. You can get extreme amounts of value out of them but you have to learn how to use them. Many tools are this way.

It might make sense to learn now, before everyone expects that you be an expert with this tool in order to do your job. On the other hand perhaps they will be easier to learn if you wait.

There is an incredible amount of nuance to be had in using LLMs and we reached the stage, probably only in the last few weeks where all the pieces have fallen into place such that if you are skilled at using the LLMs just about all of the previous problems with them can now be easily mitigated. If you learn how. There is a lot to learn.

how does one learn to mitigate not understanding the work they push , given that the work wasnt performed by them ?

By requiring the LLM to prove your requirements true mathematcially.

https://github.com/bendlang/bend

openai has retracted many of their lean proofs for the big drop of supposed novel mathematical solns. if frontier ai screws it up , how does this inconsistency manifest in weaker models?

"It might make sense to learn now, before ..." Since 2023, everything learned in Year X was 99% useless in year X+1.

"we reached the stage, probably only in the last few weeks where ..." This has also been said every other month since 2023.

I wouldn't say that's true at all. My critical reasoning skills have improved immensely as I have learned how to find the flaws in the LLM's logic, and I am much better at code review in general than I was when I first started letting agents write code.

It really is like working with an over-eager employee. They just also happen to be a pathological liar.

> Since 2023, everything learned in Year X was 99% useless in year X+1.

Personally I disagree with this. I've been using LLMs the last few years and learning a lot about techniques for getting value out of them. Even though they weren't very good for a while they seemed worth learning to me because the rate of improvement was so fast. We've now reached a point where if you know how to use them right you can get lots of value out of them.

I really don't mean to be rude here but consider perhaps the reason why you're having trouble seeing why they're valuable is because you haven't used them enough in the last few years or kept up with the developments closely enough. Maybe I'm wrong. But consider it's possible you are too.

> This has also been said every other month since 2023.

I'm sure others have said that but my perspective has been that the models are not quite good enough yet, for a while but that the trajectory is so crazy that it made sense to make the bet and invest lots of time into learning how to use them on the assumption that they would soon be good.

Even now I would say they have a long way to go. What is hard but possible today will be easy tomorrow. But quite a lot is now possible with the right techniques. Crazy things.

I remember using LLMs a couple of years ago, back when there was no mention of "AI" in our country whatsoever. Not that much mention of it online either (much less widespread). I felt like I was holding a magic wand nobody else knew existed. :P

Sounds like a skill issue.

This product is proof that you apparently either don't know how to use AI, haven't used it within the last 3 months, or don't know what you're talking about.

I just wrote a clean plugin in Rust. I don't know rust. It took work to avoid, remove, and replace slop, avoid spurious and pointless tests, etc. It wasn't "fire and forget". but it wrote the code, the code has been made clean, integrates well with existing project structure and does what it's supposed to. I spent a day or two on it, but had I attempted to write it from scratch, even knowing rust, it easily would have taken me longer.

Considering that I don't know rust at all, it's awesome.

Once a week, I tell Antigravity (3.8-flash) to rewrite every code comment and documentation that was changed in the past week. Neither GPT nor Claude can write like a human.

Neither can Gemini.

Gemini models have consistently been the best, by far, at writing and explaining.

Best against other AI output, still not even close to what a human would write.

Okay, describe one quirk of Gemini-ese that makes it stand out?

If you use it often enough, it becomes quite easy to tell. For one, when using it through the chat interface, it always congratulates me on my amazing insight in the first paragraph or at least has a very forthcoming tone. It also has a fetish for numbered lists whenever attempting to make a point, which usually contain 3 items, sometimes 2. It's also quite good at making relatively unhelpful ASCII diagrams on a semi-frequent basis.

That said, I do genuinely enjoy brainstorming with it, and these quirks are not really a hindrance. If anything, the sentiment in the first paragraph is quite useful to quickly get an insight about where I stand with my thoughts, relative to the available knowledge that Gemini has access to.

Eh, I think the tutorial is pretty readable? It's concise enough.

With the tutorial, the summary also makes more sense. I have not read the other parts yet, but so far I like what I see.

All is in pretty good taste, and I like what I've seen so far. I do not care if the author himself came up with the idea, or if AI came up with it and the author approved.

I do not understand why you "have to" know this to make use of it. You can judge ideas independently of where they came from (and you should).

This is actually a really good point that I think many people fail to understand these days!

> You can judge ideas independently of where they came from (and you should).

You can but in practice nobody does this because they don't have time. For example, once you have investigated ideas from a crank a couple of times - you don't do it again. Life is too short.

I found the language to be difficult to read, there are phrases that don’t make sense in context. It’s not concise. I also don’t care whether it was written with AI or not, and there are plenty of terrible docs predating AI. However, I wouldn’t call this documentation “good”.

100%

Couldn’t make it more than a few sentences in before the bile started to build up in the back of my throat and I had to back out. It’s shocking to me that people knowingly post unedited Claude-slop drivel and are seemingly unashamed about it. In 2026, it seems the main role of technical humans should be to act as a barrier between our agents’ output and other humans.

Do you not use Claude at work for hours a week? I find the writing style familiar, thus comfortable.

The version of the documentation which I would very much like to see would be a Literate Programming version where all the code is explained from the ground up.

Apparently, this can actually assist the LLM:

https://silly.business/blog/we-should-revisit-literate-progr...

as discussed here previously:

https://news.ycombinator.com/item?id=47300747

That's a great idea. I wonder if any major library (or language) has attempted a version their site in that style.

I'd love to experiment with this myself.

I've been trying to collect Literate Programs collected as books at:

https://www.goodreads.com/review/list/21394355-william-adams...

Note that ICC, a C compiler, is one:

https://www.goodreads.com/book/show/522102.Retargetable_C_Co...

Note that one can look through projects tagged as Literate Programming by using the topics view:

https://github.com/topics/literate-programming

might be there's something useful there.

> might be there's something useful there.

There is! As of now, if you sort by recently updated, my literate programming project is the first result :P (link in profile if anyone reads this later)

In the interest of full disclosure, my own project is in there as well (but nowhere near the top and it's a kind of obscure topic, so not likely to ever get there).

I would probably go down the Lojban route though!

I do not think you know who this guy is

We as a society have to cut this low effort commenting out. The documentation is perfectly comprehensible. What action would you take differently if a given feature were implemented by Claude, or a human?

As I said in my message, it would determine whether I use the project or not. I need to match it to my use cases, and if I find a match I need to know: is it matching because my use case falls in the domain of what the human collaborator wants from this project, or is my use case a hallucination that will go unsupported?

You cannot tell either from the AI written docs. I'd rather OP gave a rambling post about some problem he has in gamedev that led him to think a new language was needed, why the constraints are different, and how this will improve X, Y, or Z in his own words. Then I can infer what this project is and where it is going. Right now, I have no clue.

The docs are perfectly legible and to the point. I don't see the need to waste the author's time with aesthetics

Legibility is not the concern. The issue is whether the point the docs are making are the actual point the author is concerned with.

literally the first point under Why Goose -

"Faster than C++ and than safe Rust, ..."

perfectly legible ?

With respect, what on earth are you talking about? The documentation is clear about what the language does. You can download it and test it out if you like, and verify if yourself if the documentation matches the feature descriptions. What the human collaborator wants is immaterial. You get the code.

The author has written that post about why the language came about. He doesn't owe you that, but he did it anyway. He doesn't owe you anything more. You can use it or not. Advising him to throw away all the documentation and rewrite it again by hand from scratch so that adastra22 can deign to examine it further is ridiculous.

If you have a question about whether or not this further iterations will fit your specific (and so far undescribed) particular use case, the correct avenue for that is to ask the author politely. Or Fable; Fable could probably tell you without having to bother the author. But holy cow, the entitlement.

Are we now in a situation where all code is disposable, throwaway things with no long-lived projects?

We're talking about a programming language. Languages, and their compilers, evolve over time. Where is this one headed?

If you think you'll be able to divine that if and only if the documentation is entirely written by a human, then I'm afraid I'll have to disappoint you: no language has ever evolved strictly according to the initial plan of their authors. Nor has any author's strongly held belief about the future ever panned out the way they thought. Nor has the documentation ever held the immutable future of the language, even when fully human generated (which essentially zero languages have, even before AI).

The way to find out if a language is suitable for your needs is not to demand, in an entitled way, that the author perform an act for you. It is to (a) ask the author politely; or, failing that, (b) to examine it yourself (or ask Fable to evaluate it, using tokens you paid for).

This particular language, further, is Apache 2.0 licensed. If it's not working for you, fix it. Jesus.

Your correspondent keeps moving the goalposts and never presents a coherent argument. I would just leave them be.

How have I been inconsistent?

pretty much that's the default assumption yeah. Anything new is probably a throwaway. If there's anything cool in it - rebuild it to your own taste. There will be exceptions that do become long lived projects of course. probably even the same amount there were before. But there's going to be a few orders of magnitude more throwaways so on average any new piece of code is going to be a throwaway

Do you not see the problems that arise here? Are we losing our accumulated engineering best practice knowledge? Standardized, common, highly reviewed subsystems provide working engineering know-how and accumulated lessons learned. Not even the best AI systems can keep that many considerations in mind when re-spinning code.

If this is your default assumption, I hope I never have to rely on code you generate.

Who said it's my assumption for code I generate? We're talking about how I evaluate code other people generated. If that wasn't my default assumption - then you should never trust anything I create because I would be naively trusting other people to maintain throwaway projects.

Are we losing our accumulated engineering best practice knowledge? Yes. Have you seen the quality of new hires recently? The ones who've cheated their way through school and don't know what a for loop is? People that have those skills aren't letting them atrophy but the chain of transmission is in crisis. Breaking news, sometimes things suck

with programming languages which just rehash ideas (not saying it's a bad thing mind you! a good mix is better than a sum of its parts) you can nowadays get literally years of work in a week. truly novel stuff like bend2 takes longer (ask Victor), but I expect the next generation of models to compress those timelines, too (if the next generation is allowed to be released, since the security brouhaha going on now is seriously concerning)

Seems like an AI could be tasked with verifying the docs. Then a human can double check it's work if it finds anything.

Verify against what? What I want verification against lives in the human's head, not the repo.

Oh, I was thinking verify what the doc claims to what the code actually does, I misunderstood you.

What's left to determine? Obviously AI written docs are a deal breaker for you. Seems very straightforward. If docs are ai written, move on. That's an immediate and obvious fundamental incompatibility you have with the project. Why are you still complaining about the docs being ai written getting in the way of making your decision when you've clearly already made it?

Why are low effort comments not worthwhile but low effort docs are fine?

If you've ever been tasked with coming up to speed on a system mostly documented with AI writing, you'll quickly realise how hard it is to trust anything you are reading. Even if the Claude documentation is 100% accurate, you'll never shake the worry that some crucial fact you founded your understanding on was wrong. It's a fast recipe for psychosis.

That's without even mentioning that AI writing can often state the what but not the why. That human perspective is usually the most valuable knowledge to get across in writing.

There’s no reason to trust a human any more than an LLM for this. Humans are not 100% accurate and very capable of making crucial factual errors in documentation. Ask me how I know.

There’s a _very_ good reason. Humans have a much richer mental mental model of the codebase, design decisions, external factors, etc.

Of course Humans can make errors when translating that to English. But if you’ve read any amount of Claudish it should be obvious that interpolating the code to documentation with an LLM typically produces a significantly worse result in almost every way. Except for superficially “sounding” correct.

That’s just not true especially when the author designed the language with the LLM like he says in the end (the AI is very good at forcing you to be specific and make decisions on ambiguous terms): all decisions can be included in the repository in a way the computer can follow and understand, which is a pattern called specification graphs. You can just document things in the docs as well if you want a more basic method. If you are claiming this language is worse in every way than others that were made by humans alone, could you be specific?? What are the bad things you’ve found? What part of the docs are incorrect? Or are you just commenting without having looked at any of that?

That is not necessarily true if the codebase is written by AI unless the human chose to be involved. That was also not necessarily true before AI either. Human skill level is wildly variable

Above all, I think I like human docs because then I not only know someone has a deep understanding of it, but also that someone can actually be queried about it. With Claude, there is always the accountability problem. If something seems off, do I even have someone other than Claude that understand it all and who is accountable ?

I don't want to read software written by misanthropes. If you've given up on working with other people, then what is the point exactly?

Amen. Not to mention these people usually want others to laud them for creating a world they can't bring themselves to actually live in.

If you believe you are making something worth other people's time, you should ALSO believe you are making something worthy of your own time.

we need an equivalent of the medieval "stand under the bridge you built" trust system.

would you fly in an airplane if the software was written mostly by Claude?

If an engineer who mostly used Claude left the company, can his replacement understand his mental model, given that he himself doesn't ?

It's probably possible to prompt an LLM into writing well, but most LLM writing that I've seen is poorly structured (e.g., the paragraphs in this post feel like strings of punchy marketing phrases), and the LLMs are too good at sounding like they're saying a lot while saying very little.

Plus, if a human puts the effort into writing something, that signals to me that it's worth something, because human time is much more scarce than LLM time.

I recently saw a language posted that caught my interest. I went into the docs and read the page "How X compares to Y", and Y is my favorite language

Within the first couple of paragraphs and bullets it made a completely false claim that is the opposite of how the language operates, something any person that knows the essentials of it would know. Language Y was listed in the front page as an inspiration (and I don't doubt them) but clearly they either did not read the docs the LLM wrote or did not use the language for long enough to know it has zero structural typing

at that point i just ask an ai questions about how the system works and hope the reasons for particular decisions can be reverse engineered from git history/pr comments etc.

I find your comment much much lower effort than GP you took a snip at. It's true that more ppl may align in your thinking, but dissing the other side's concern as low effort does not belong in hn.

> What action would you take differently if a given feature were implemented by Claude, or a human?

This one is easy: I'd read the docs if it were written by a human, but I won't read them if they're written by Claude.

Comprehensibility does not equal correctness or fitness. As if that wasn't enough, or perhaps in most related manner, an LLM/AI cannot be held responsible for what it produces, by nature, especially considering the fact that a _human_ claims all of it as their own work, or at least take responsibility. Meaning that when a parable of documentation is discovered to be bogus, you can't pin it on AI, you go to the human and ask them why the documentation is wrong, and it's not a good look.

> The documentation is perfectly comprehensible

For a programming language? It's subpar and you know it.

See this for a language docs site by a small-ish team, but a significant effort was put into making it nice to read: https://tour.gleam.run/everything/

> The documentation is perfectly comprehensible

That's, like, a stunningly low bar for documentation. "The vehicle is perfectly capable of performing motion, why are you complaining?"

Reply on news.ycombinator.com