[simplotek]

> Rust's documentation is taken very seriously and often praised! But we focus on documenting actual APIs (with examples that we actually run in CI to make sure they don't break!) (and links to the actual implementation to dig deeper!).

Your confusing two radically different types of documentation.

Specifications, such as the ISO standards for C and C++, are the source of truth of what determines what the language actually is.

Writing tutorials with example code ran in some implementation might help people onboard onto it but it does not, in any way, shape, or form, specify what's the language.

It's like comparing blueprints of a construction site with random videos and photos of the same building.

[Sharlin]

I don't think Gankra is confusing them as much as asserting that a full specification should almost never be required reading for a user of a language, just like you don't need the detailed blueprints of a building to live or work there, or even to do simple repairs or redecoration.

A detailed specification only matters if you're trying to construct another building to the same spec (write another compiler), want to do heavy renovation work (implement a major new feature on rustc), or if the technical details are insufficiently "abstracted out" (say, there are exposed live wires that you have to know to avoid in daily use – cf. undefined behavior in C and C++).

[simplotek]

> I don't think Gankra is confusing them as much as asserting that a full specification should almost never be required reading for a user of a language (...)

My point is that this line of argument makes no sense.

It's like claiming that dictionaries and English grammar books are not needed because kids learning their ABCs almost never require reading those to learn how to speak English.

Rust standardization opponents insist in these moot strawmen arguments. They completely miss the whole point of a standard. Standards are critical because how things work need to be specified in precise terms that are set in stone. Standards are read to gain deeper understanding of a language. They are used to clarify corner cases and obscure issues and behavior. You do not need a ISO standard because you want to write a "hello world". You need an ISO standard because you are a mature professional that understands that "it works on my machine" is not an acceptable answer to any question you have on how a programming language supposedly works.

[tialaramex]

> It's like claiming that dictionaries and English grammar books are not needed because kids learning their ABCs almost never require reading those to learn how to speak English.

I don't think this makes the case you were hoping for?

Both Dictionaries and actual "English grammar books" (not pedantry written by non-experts like Lynne Truss) are descriptive because English is a natural language. I don't own the full Cambridge Grammar of the English Language but here's an extract from the Student's Introduction which I do own. (The Introduction is intended to be suitable as an undergraduate text)

"... it isn't sensible to call a construction grammatically incorrect when people whose status as fully competent speakers of the standard language is unassailable use it nearly all the time".

We don't use these books to teach children or ESL (English as a 2nd language) learners. My employer runs "pre-sessionals" which are short language courses for overseas students, they have a conditional visa, they fly in a month or two before term starts and they take our intensive ESL courses, if they do OK they're signed off as able to successfully use English, they start their degree course (say, Electronics) and the visa conditions check off, if they can't hack it the visa conditions terminate their stay and they are sent back. This allows us to recruit foreign students who could, if they apply themselves, be successful - without them needing to somehow find local English tutors in their home country, squeeze in learning a foreign language and convince immigration they've learned enough English to follow their degree course.

It is not the goal of pre-sessionals to teach a Chinese teenager to say "It is I" rather than "It's me" because that's a weird hyper-formal English. It is the goal that they should understand phrases their tutors and peers might use, which are often going to be informal or even somewhat non-standard, and be able to express themselves in both formal and informal contexts. They should be able to read say an Economist article, write a 1000 word summary of the article and talk about it in conversation.

Books like CGEL and dictionaries represent our understanding of how a very complicated system is actually used by real people. They are not guides to how English should work, such a document would be very silly.

> Standards are critical because how things work need to be specified in precise terms that are set in stone.

This is a mythologized version of what's going on. If a language is spending huge amounts of money and personal effort on the ISO process I can understand they'd want to project this myth, but it isn't true.

For C++ in particular - the most obvious comparison from the ISO standard languages to Rust - huge swathes of important stuff is "ill-formed, no diagnostic required" in the standard. If your C++ program falls foul of any such clauses, anywhere, even once in some obscure sub-routine you don't use, too bad your entire C++ program has no defined meaning and the compiler is not expected to report this as an error or warn you about the trouble you're in.

Let's use my favourite modern example. Suppose we've got a std::vector of float, and we sort that using std::sort but in some cases, due to an oversight, one element of the vector can be NaN. In C++ 20 Our entire program is undefined and anything might happen because of clauses introduced by the C++ 20 Concepts feature. Our program probably works fine in practice, but no thanks to your "critical" standard.