Hacker News Reader

Comment by steveklabnik | Hacker News Reader

> A big problem with Rust right now is that the documentation is awful.

Could you get more specific for me, please? There's certainly much room for improvement, but I can't fix what I don't know about!

> If you have to clearly explain in writing how something works,

Are you aware of our RFC process? Changes _do_ have to have extensive, written explanations.

View on HN

FWIW, I've found the Guide incredibly helpful, and in general found the docs very satisfying. (Although I do wish the pointers guide was more complete :) )

The API docs + search in the docs are incredible IMO. I'm in absolute love with rustdoc. Having links to the source right there is the most valuable thing ever, both when trying to understand how to use a given API, and when trying to write similar things its really useful to be able to look at how others have done things.

Awesome. I'll consider bumping up the Pointer Guide in my priorities.

I personally usally find myself searching http://doc.rust-lang.org/std/. One problem I sometimes run into is that the search seems to do fuzzy searches and generates an often overwhelmingly long list of not all too helpful items. E.g. search for "vector" -- a basic building block in rust. The most relevant entry "std::vec" is far down the list. It's also unclear to me, what "experimental" (std::vec) and "stable" (std::vec::Vec) are supposed to mean. Also, during my very first foray into rust, it was not evident to me how the various parts on the page belonged together. Newcomers often are blind to what is evident to the expert.

I also think there should be a consolidated guide, which users can download as PDF and maybe print out (Maybe I'm somewhat old-fashioned in this respect) -- an always up-to-date go-to reference that explains the ins and outs of the language. I don't want to browse 20 guides/tutorials that may or may not contain the info I'm looking for.

Yeah, we do a fuzzy search, so it can be weird. To answer your specific question, std::vec is the module, and std::vec::Vec is the actual struct itself... so the module is overall unstable, but the struct itself is stable. If that makes sense.

Have you seen "The Guide"? It's about 100 pages long, and we used to produce a PDF, at least...

I think people expect _more_ documentation. The guide can only get you so far IMHO.

That said, if I may say so, string handling should be more throughly detailed. It's one of the first thing new comers will stumble upon. Especially for those who come from a dynamic language. Heck, I think it might even been the perfect occasion to exemplify the borrowing system.

Edit: Just some further thoughts on the spot (feel fre to ignore if you strongly disagree).

It feels at the beginning that the guide is kind of building things up. In that spirit I would put an expended String chapter just after "7 Comments" since simple example programs can already be made without what's following (well except maybe loops). Maybe something in the spirit of "14 Guessing game" but smaller. That is, with less, more recently read, concepts to refer to.

Have you seen http://doc.rust-lang.org/guide-strings.html ?

(And you're right, the Guide is intended to only get you to mid-level stuff)

Reply on news.ycombinator.com