
Rust’s documentation is about to drastically improve - steveklabnik
http://words.steveklabnik.com/rusts-documentation-is-about-to-drastically-improve
======
adamnemecek
Here's my suggestion that I strongly believe could help Rust's (or any
platform's for that matter) adoption:

There should be a list of somewhat larger projects (similar to the sample apps
for Cocoa
[https://developer.apple.com/library/mac/navigation/index.htm...](https://developer.apple.com/library/mac/navigation/index.html#topic=Sample+Code&section=Resource+Types))
maintained by people who actually understand the language. For me, and I
imagine a lot of other people, the hardest part about learning a new
language/platform is getting from the stage where I understand the syntax and
APIs to getting somewhat proficient with it and being able to make informed
decisions about how things should be done in that language.

A lot of times, when I look at some open source projects to learn from, I'm
left with the impression that the author might not have really understood what
s/he's doing and that really increases my frustration with the platform. A
list of canonical projects would prevent this.

I'm aware of Servo but I feel that Servo is a.) too large of a project for a
Rust n00b to learn from b.) it's not always up to date WRT to the language
version and the best practices.

Alternatively, this could also be a list of 3rd party projects blessed by the
Rust people as good projects to learn from.

While it might seem like a waste of time, I feel like this would e.g. reduce
the number of people needing help on IRC or the mailing list so it might
actually save time.

~~~
netcraft
I completely agree. 9 times out of 10 I can pick up a new language, understand
the syntax, but how to idiomatically structure a project is a completely
different thing. Most of the time I would rather have the latter than the
former - I can pick up most syntax from its actual use.

~~~
steveklabnik
> how to idiomatically structure a project is a completely different thing.

Agreed, and I plan on explicitly tackling this too. That'll come after Cargo
is a bit more solid, however.

~~~
charlieflowers
steveklabnik, along these same lines, I've come across the claim that things
like map, reduce, fold, etc., are not idiomatic Rust. But nothing about why or
why not that might be true. That kind of guidance would be valuable,
especially since Rust borrows so many concepts from functional languages.

~~~
steveklabnik
I will certainly say that Rust is young enough that idioms are still forming,
so beware of those who say anything is strongly idiomatic. Except four spaces,
no tabs. That's _incredibly_ so. ;)

But yes, as they develop, I'll be encouraging the use of idioms directly in
the documentation. My years of Ruby make me a big believer in developing and
following idioms.

Oh, one last thing about that: iterators are way better than explicit loops in
Rust, because loops have to do bounds checking, but iterators don't. So
generally, iterators are not just better stylistically, but also performance-
wise too.

~~~
munificent
> because loops have to do bounds checking, but iterators don't.

They still have to check something to know when to stop iterating, though,
don't they? You may have traded a bounds check for a dynamic dispatch or some
"is done" check, but there's still some conditional logic each iteration isn't
there?

~~~
Dewie
Bounds checking is different from the conditional checks in something like a
loop. It's the logic that prevents you from accessing memory that isn't yours.
If you have an array arr of length 5 in Java, if you do arr[10] you get an
IndexOutOfBoundsException because you're not allowed to do that. If you did
the same thing in C, you might get some data which is unrelated to your array,
or perhaps a segfault.

So when you you loop over an array, your loop conditional makes sure that your
index hasn't indexed out of bounds, _in addition to_ the bounds checking that
is performed when actually indexing the array. So you in a sense pay a double
price for the same assurance. (This is modulo compiler optimizations.)

Rust has to guarantee memory safety (I guess Java makes the same promise).
This means that you have to have bounds checking for array indexing, lest you
index out of bounds of some array and get killed by the operating system, if
that memory happens to be outside of your process' "turf". You can't eliminate
that in general (or; it's hecka hard), but you can probably encapsulate things
like iterating over data structures like arrays, vet the code, and say that
"this thing loops from 0 to the length of the array minus 1... I swear on my
mother's future grave that it is safe to turn off bounds checking for array
indexing here." (The way they do it in Rust may be more rigorous than this,
for all I know!)

~~~
pcwalton
> I swear on my mother's future grave that it is safe to turn off bounds
> checking for array indexing here." (The way they do it in Rust may be more
> rigorous than this, for all I know!)

The hard part about doing that is that it's only safe if the array is
guaranteed not to be mutated during the loop. Rust enforces this through its
borrow checking system.

------
thinkpad20
I'm very excited to hear this. Rust is a very promising language, and having
good documentation really helps make the difference. I actually got a lot out
of the tutorial for Rust when I read it, but there were a number of things
that were out of date, and others that weren't covered at all. Rust for
Rubyists was also a great guide when I poked through it a while back.

I think one of the sources of success for Golang is its "hit the ground
running" approach which takes you from zero to hacker in a short amount of
time. Rust is considerably more advanced than Go, but there's no reason that
it can't adopt a similar attitude of pragmatism and real-world applicability
(although its libraries might lag behind Go's). Having first-rate
documentation is a huge step in that direction and a very promising
development.

~~~
steveklabnik
> I think one of the sources of success for Golang is its "hit the ground
> running" approach

Agreed! One of the weird things about Rust is that it's been open source since
the beginning, where languages like Go and Swift have been closed for years
before having their first release be very polished.

Rust will get there. Like most things, it just takes time and sweat.

~~~
mseepgood
Go was started in 2007 and opened in 2009 (2 years closed). Rust was started
in 2006, Mozilla became involved in 2009 and it was opened in 2012 (6-3 years
closed).
[http://en.wikipedia.org/wiki/Rust_(programming_language)](http://en.wikipedia.org/wiki/Rust_\(programming_language\))

~~~
dbaupp
2012 was just the first 0.1 release, it was public before that. Also, Rust is
doing more interesting/experimental things than Go with significantly more
iteration and change.

~~~
kibwen
Can confirm, I've been involved in Rust since 2011 and Mozilla at large began
talking about Rust (publicly, though without great fanfare) in 2010.

Furthermore, saying that Rust has been worked on "since 2006" is misleading.
From then until 2009 it was just the work of one man idly tinkering in his
free time, hardly a serious project.

------
Argorak
If you are building a new language with serious ambitions for usage, you
should really take a look at how well the Rust community has turned out to be.
The "Buzz" you experience around the language is largely fueled by lots of
enthusiasts - e.g. hop on the IRC channel at any time of day and get help.
There are no dumb questions, especially about changes that happened in the
mainline 2 days ago.

Barriers for committing to Rust itself are very low. Also, they aggressively
moderate their spaces according to their CoC. A few days ago, I asked a rather
picky question on their subreddit and was quite surprised how on-point and
serious the answers were. Given that the topic had the potential for some
trolling, it was surprisingly calm.

It's really a community I am happy in.

Edit: I got a bit excited. Obviously, the point of the whole thing is: Mozilla
investing into Rust docs seriously and Cargo really shows that this is not an
lab language anymore.

------
gnuvince
Great job Steve! If you don't have them yet, get a copy of Strunk and White's
"The Elements of Style" and Kernighan and Ritchie's "The C Programming
Language". I'd love my Rust documentation to have the same level of
conciseness and clarity.

~~~
omaranto
Having read some of Steve's excellent documentation already I'm sure the
advice in it makes more sense than Strunk and White ---see
[http://chronicle.com/article/50-Years-of-Stupid-
Grammar/2549...](http://chronicle.com/article/50-Years-of-Stupid-
Grammar/25497/)

------
pnathan
Congratulations!

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! ;)).

~~~
charlieflowers
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.

~~~
pnathan
I actually find the whole kata code sample thing to be _entirely_ inverse to
how I learn. I typically learn by principles first.

Others entirely differ. And that's A-OK! :)

~~~
charlieflowers
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.

------
rubiquity
That should help the language grow.

As an aside, what does this mean for your position at Balanced?

~~~
steveklabnik
I left Balanced a few weeks ago. I really loved the team, the product, and the
work, but I couldn't stand living in San Francisco. I wasn't really doing
development work at Balanced, so remote didn't make a whole lot of sense,
either. I really want to dis-associate my work requirements from time and
space, rather than need to be physically present at an office most of the
time. Sometimes, things just don't work out, even when everyone involved wants
them to. I still hang out in IRC and even answer questions from time to time.

I elaborated here:
[http://words.steveklabnik.com/sf](http://words.steveklabnik.com/sf)

------
onan_barbarian
Fantastic. Keeping the tutorial up-to-date with the language and of high
quality is just about the best possible thing you can do for documentation.

Nothing puts me off from a language or system quicker than clicking through to
a tutorial that is either (a) extensive but 2-3 versions out of date or (b)
hopelessly cursory ("here's 2 pages of neat stuff, see you later").

------
Jemaclus
Can't wait. I played around with Rust when it was in 0.9 and 0.10, but wound
up falling off the wagon around then. Stuff was changing too much for me to
keep track, and the documentation wasn't always the best. I'm really, really
looking forward to 1.0 and better documentation!

------
mrinterweb
If the documentation will be on a hosted site, I would recommend adding the
ability for supplemental usage examples of the API provided by the community.
Comments on php.net's documentation site and on apidock.com have been helpful
for me in the past. Obviously, user usage comments are not always helpful, but
sites sort the comments based on what other users find helpful. In my opinion,
having the primary documentation with supplemental community supplied usage
examples is the best way to do documentation.

~~~
steveklabnik
It's been a while since I used PHP, but many of those examples are _very_ bad,
and encourage very poor practices.

I plan on having examples built-in with the documentation for everything, but
actually approved by the team, rather than just as comments. They'll be much
higher quality that way.

~~~
mratzloff
One of the things I love about Go's documentation is that all examples are
runnable in the Go Playground, right there, inline. You can take an example,
modify it, and see how things change. Rust would benefit greatly from that
same functionality.

It also forces documentation to be up-to-date; one of the reasons I selected
Go over Rust a year ago (besides more mature libraries and better
documentation) was the fact that Rust seemed to be rapidly changing.

~~~
steveklabnik
Our home page already has this, go try it! [http://www.rust-
lang.org/](http://www.rust-lang.org/)

> Rust seemed to be rapidly changing.

Yup. That's what happens with a pre-1.0 language. :)

------
yazaddaruvala
While it can definitely be improved, I found this the best resource to learn
Rust.

[http://rustbyexample.com/](http://rustbyexample.com/)

~~~
yazaddaruvala
To elaborate, in contrast to the official tutorial. The trick it plays on you,
by hiding most of the list, is really nice when you first land on the page.

I guess I like the bite sized chunks and the organization by concepts.

Although, I never know when there is more info about the current section under
the fold.

I hope thats helpful.

------
dj-wonk
A meta suggestion: please make the article's date easy to see. (The timestamp
is hidden until you mouse over the title: Jun 16, 2014.)

~~~
steveklabnik
Thanks! I'm just on Svbtle, so I can't do that.

~~~
dj-wonk
I wonder if Svbtle thinks visibility of a timestamp is unimportant? (Never let
useful content get in the way of a good design!)

------
Dewie
> I’ve often found that I start with documentation and then move into
> contributing code, once I get my head wrapped around everything.

Sounds like a good approach, in general.

