I'm working on my first non-trivial system with Rust right now, and I'm finding that the learning curve related to the borrow checker and lifetimes is rough. I'd liken it to macros in Common Lisp, but not quite as a cliff as monads.
In other words, I would like to ask that a substantial amount of your time in documentation at some point be pointed at the lifetime & memory system, as it is, IMO, the really unusual and hard part of Rust (As well as the whole freaking point of it too! ;)).
Yes, as you mention, the lifetime system is the big issue for newbies in Rust, and also a large part of the point! Revamping those guides is high-up on the TODO list.
I also suspect that lifetimes are one of those features that people might say, "I learned Rust, and I don't code in it, but learning about lifetimes improved my code in $DAYJOB_LANGUAGE." Just like how I think Haskell improved my ability to program in a variety of other languages, but I don't really write Haskell anymore.
This topic would be well served by something like "katas." A series of code samples that look (to the noob) like they should compile, but don't. The series of samples would be chosen to walk the learned through the surprises in pedagogical order.
Actually, that's my preference too. But for certain topics, even after you grasp the principles, there are certain things that are going to surprise you until you get more experience. You can identify these in advance and find they will surprise most learners. So the kata approach is supplementary, kind of like well chosen exercises in a good textbook.
I'm working on my first non-trivial system with Rust right now, and I'm finding that the learning curve related to the borrow checker and lifetimes is rough. I'd liken it to macros in Common Lisp, but not quite as a cliff as monads.
In other words, I would like to ask that a substantial amount of your time in documentation at some point be pointed at the lifetime & memory system, as it is, IMO, the really unusual and hard part of Rust (As well as the whole freaking point of it too! ;)).