Comment by adastra22
12 hours ago
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.
>>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
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"
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
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.
That's like me with violins!
Maybe violins don't write good code after all?
it's definitely true in real life. i think there is actually a massive skill gap in using them effectively.
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.
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!
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://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 do not think you know who this guy is
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.
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?
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.
5 replies →
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.
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
1 reply →
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.
6 replies →
Seems like an AI could be tasked with verifying the docs. Then a human can double check it's work if it finds anything.
2 replies →
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?
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.
Why are low effort comments not worthwhile but low effort docs are fine?
> 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/
> 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.
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.