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?

▲

spuz 3 hours ago | parent | next [-]

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.

▲

JojoFatsani 2 hours ago | parent [-]

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.

	▲	foltik an hour ago \| parent [-]
		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.

▲

adastra22 3 hours ago | parent | prev | next [-]

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.

▲

hexasquid an hour ago | parent | next [-]

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

▲

adastra22 an hour ago | parent [-]

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

	▲	hexasquid 25 minutes ago \| parent [-]
		Oh, I was thinking verify what the doc claims to what the code actually does, I misunderstood you.

▲

knowsuchagency 3 hours ago | parent | prev | next [-]

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

	▲	adastra22 2 hours ago \| parent [-]
		Legibility is not the concern. The issue is whether the point the docs are making are the actual point the author is concerned with.

▲

felixgallo 3 hours ago | parent | prev [-]

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.

▲

adastra22 2 hours ago | parent [-]

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?

	▲	felixgallo 44 minutes ago \| parent [-]
		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.

▲

condwanaland 3 hours ago | parent | prev | next [-]

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

▲

fuzzythinker an hour ago | parent | prev [-]

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.