3 ms·
I've tried learning Rust twice. Once when 0.4 was announced, and then again a few days ago because of 0.6. Both times I read the entire tutorial and manual, and
by eridius 14y ago
I've tried learning Rust twice. Once when 0.4 was announced, and then again a few days ago because of 0.6. Both times I read the entire tutorial and manual, and poked around the standard libraries. But both times I ran in to the same problems. Both the tutorial and manual contradict each other in places, and contradict themselves in places too (e.g. I saw both &'r foo and &r/foo syntaxes in the 0.6 manual). The manual is also full of broken links (every time it referenced another section of the manual, the link didn't actually do anything). And the tutorial doesn't actually have anything for you to do as you work along it, it's basically just a rephrased manual with a bunch of tiny code snippets. The library documentation is formatted really poorly and makes it hard to figure out how you're supposed to do something. And just in general, there's no good examples of how to actually write idiomatic Rust code, or how to write a full program.
I recognize that it's a work in progress, which does excuse a lot, but these problems do act as a significant barrier to actually using the language. I'd love to actually start writing Rust programs, but when I look at it, it just feels like I'd be better off waiting until the next release and hoping it's better. Which is a real shame, because a lot of what you're trying to do with the language really appeals to me.
Contrast this with the state of the Go documentation / learning material when it was announced. I was able to dive right in to that language, figure out how to write idiomatic code in it, and produce programs.
I guess what I'm trying to say is, I wish you guys would start putting more effort into the documentation side of things.
- fzzzy 14y agoAs Patrick said, Go was announced much later in the development lifecycle. Go was developed for quite a while before it was announced. At Mozilla, we do things a little differently. All of our projects are open and public from the very first commit into the repo. People seem very excited about Rust and want to use it right away, which is great, but things have been changing a lot, as you noticed, and will continue to do so for a while. One of the reasons things are changing is because the Rust developers take into account the opinions of random early adopters of the language. There is no idiomatic way to write Rust yet because Mozilla wants the Rust community to help figure out what idiomatic code should look like. Go, on the other hand, has lots of opinions. There are obviously tradeoffs to each approach, and one downside of the Mozilla approach is a lot of churn and chaos sometimes. However there are a lot of benefits too, one important benefit being that the community is helping to shape the language in an open way.
- eridius 14y agoI have no problem with the community helping to shape the language. But I think the difficulty in getting started with the language, due primarily to documentation problems and lack of good introductory material, is going to make it harder for people to get involved. I know when Go was first released I immediately jumped in and started using the language. I was even the first non-google, non-@golang person to get their name in the CONTRIBUTORS list (because I wanted to modify the emacs go-mode, but still). But I feel like I can't even get started with Rust because I have no idea what I'm doing and the documentation isn't helping. For example, right now I'm trying to whip up a really tiny program to test out the FFI. But the libc module's documentation is completely nonexistent. It's just a series of nested modules, which end up having nothing in them. I'm sure there's actually stuff in the modules, otherwise they wouldn't exist, but the documentation claims that they're empty. So I have no idea what I'm doing.
- pcwalton 14y agoThe problem with libc is twofold: first, reexports don't show up in the docs (bug on file [1]), and secondly, that every module gets a separate page (filed as [2]). You can actually see the signatures for functions if you click through enough, e.g. http://static.rust-lang.org/doc/0.6/core/libc_funcs_posix01_unistd___foreign_mod__.html http://static.rust-lang.org/doc/0.6/core/libc_funcs_posix01_... Having to click through is annoying, though. It would be better to be able to specify that a module and all its submodules should go on one page in the docs. Thanks for the bug report! [1]: https://github.com/mozilla/rust/issues/3537 https://github.com/mozilla/rust/issues/3537 [2]: https://github.com/mozilla/rust/issues/5952 https://github.com/mozilla/rust/issues/5952
- eridius 14y agoMakes sense. Would fix the problem where I have no idea what prelude pulls in too. Also, part of my confusion with libc is that not all of the leaf modules actually have something in them. The first few I looked at were completely empty, so I thought the entirety of the libc documentation was empty.
- 14y ago
- fzzzy 14y agoOh, also, if you see incorrect syntax or broken links in the manual, file bugs!