100 days with Rust: a series of brick walls

For the languages I've used (Node and Python), I'm just comparing the ease of finding documentation on the language homepage. A typical flow is: Homepage > docs > reference/api

Node is very straightforward:

https://nodejs.org/api/index.html

Python has a library reference and a language reference:

https://docs.python.org/3/library/index.html

https://docs.python.org/3/reference/index.html

All 3 of these pages are blatantly obvious index pages. For Rust, this is where I assume you're supposed to end up (there are way too many links on the "Documentation" page, I'll address this at the end):

https://doc.rust-lang.org/std/index.html

You have to navigate/scroll to see the actual list of modules/types/macros or minimize the "about" section. The first thing that I think I should see on an API docs page is an index with maybe a very short blurb/link in regards to the prelude. If the API reference needs a "How to read this documentation" that is long enough to block you from seeing the index itself, something is wrong. Any user that clicks into an API specification either knows how to read it or knows how to click a link that says "about these docs". If they didn't, they would likely be in the "learning" section. Beyond that, the section has a list of 4 links, 3 of which are anchors (that are both out of order and already listed on the left nav) while the prelude link goes to a completely separate page.

To address the Documentation landing page, you have "Learning Rust" and "References". Learning Rust > The Rust Programming Language and References > Syntax Index effectively both go to the same page. At the bottom you have a "Project Policies". Are those really part of "Documentation"? I generally think of "language" documentation, not "organization" documentation when I see the header. I would expect a documentation landing page to be a lot more minimal and easier on the eyes, similar to:

https://doc.rust-lang.org/nightly/

What that page has in common with almost every other language documentation page that I just visited: Bullet points and/or indentation.

EDIT: I should add that I browsed around various language pages while writing this. To add some context for my opinions, I found the Elm docs to be far and away the easiest to navigate excluding the fact that they don't have links to the source code per method. I made it to their API docs without ever hitting an incorrect link. Julia was similar, but I mis-clicked on the manual rather than the standard library because everything is on the same page and neither section collapses.

Nowhere does this article suggest that the introduction is a generic example of learning to program. No. Where.

Author here. I want to apologize a bit for the tone of this article — it was written from a place of frustration, and this part of the site is very much akin to a development journal — these are short articles without a lot of concrete facts that are not really intended for broad or comprehensive consumption. In no way is this meant to be an anywhere-near comprehensive critique on Rust.

I'll quickly point out that Rust is my favorite programming language, even if reading this piece in isolation would give you the opposite impression. There are about a million things to like about it: The syntax, type safety, sober choices around language design, built-in documentation facilities, conventions, `rustfmt`, linting with `clippy`, toolchain management with `rustup`, community (in the sense of project management and organization), development momentum, ecosystem, and a whole host of other things are all downright incredible. Some of the people working around the core are undoubtedly some of the smartest throughout the entirety of professional software.

That said, I wouldn't take back anything I wrote here because even when I read it back today with a much more optimistic place (I bypassed many "brick walls" that I alluded to since I wrote it), I still think it's true. Months later, even after writing a lot of Rust, I often still don't feel productive.

No language is perfect, and it's probably healthy to have the occasional counterpoint to its fairly consistent positive press. I've spoken to people who don't know much about the language and refer despairingly to the "Rust Evangelism Strikeforce", which I think is largely internalized rationalization that what they've read is too good to be true, so there must some nefarious element at work. Rust really does deserve its good press, and hopefully the occasional dissenting opinion and subsequent discussion will help convince them of such.

IMO, Rust has a few existential threats — the one that I think most about is that despite being well passed 1.0 at this point, there's a distinct lack of pragmatism around getting core features like concurrency nailed down and shipped. Futures and Tokio are widespread at this point, but the APIs are still changing, and the error messages that they produce are still quite awful. Even once they're fully feature-complete and stable, they're still not going to be very pleasant to use — you have to think really hard about how you're doing future composition. Contrast this to a concurrency system like Go's, where you can more or less pretend that you're writing synchronous code, and let the runtime take care of the heavy lifting. I love how much careful thought and consideration is being put into the development of a cohesive concurrency model, but unless it can get to the point where it's stable and far more user-friendly, people (like me) who are trying to use the language to build things are going to continue having a hard time.

In summary, Rust is awesome, the core team is awesome, and the development community is awesome. I'm confident that the usability problems it has today will be worked out.

He's (the OP) also correct. SQL is really, really weird when you come from an imperative/functional perspective.

I've forgotten most of this as I've gotten used to SQL, but you can use variables before you define them (except when you can't (damn you group by not handling my alias)). Like all of this makes sense to me now, but it was pretty painful when I started. I distinctly remember WTF-ing my way through my first weeks with SQL.

Rust gives me a similar feeling.

By that logic, programs written in C are the most polished. Yeah, that checks out. /s