not a layer cake analogy

I’ve been following some of the #Rust2018 blog posts with some excitement. It’s kinda fun getting a sense of how we can build on our past successes to reach new heights. Closer to home, the docs team started trying to put their own goals together for the year, and that discussion combined with a few of the community blog posts brought something to my attention:

Several people have recognized that there’s a bit of a gap between “how you use the language” beginner tutorials, and “minute esoterica”/”cumulative design planning” advanced discussion. Everyone called out a lack of intermediate docs, but… i wasn’t actually sure what fell into that gap. >_> So i did what came naturally, and i asked/rambled about it on twitter.

My initial thought was that such documentation wouldn’t be about Rust specifically, but more about some other subject matter, just with the added window dressing of using Rust libraries and code samples. In other words, “intermediate” docs wouldn’t be framed as “docs” at all, but instead a deep-dive blog post that’s mainly about something else, other than Rust specifically. As someone who hasn’t really been attached to any specific area in computing, the idea of trying to write one of these myself felt rather intimidating.

There were some great responses to the Twitter thread. Here are some responses for specific ideas that people considered to be “intermediate” docs, or things that were generally lacking that were more advanced than TRPL itself:

Working from there, i dreamed up a few concrete suggestions that seem to address these:

After looking at these suggestions and ideas, i noticed something about the difference between these proposals and the existing literature, both official and unofficial, that serves as Rust documentation. I have a sense of beginner and advanced documentation both focusing on small details. With beginner documentation, the “small details” they focus on are things like basic syntax, specific language features, or how certain things interact in specific cases. With advanced documentation, you still get “small details”, but now they’re about language features that require a lot of context, or the implications of a certain feature, or implementation details of some library or feature or the like.

The key difference is one of context. The beginner documentation only needs a sense of programming topics, some experience with another language (or not even that if you’re focusing on introducing someone to programming in the first place), but nothing about Rust specifically. The advanced documentation, on the other hand, builds on extensive knowledge of the rest of the language, or the implementation of some system, or background knowledge of some field, or the like.

“Intermediate” documentation, on the other hand, seems to focus more on The Big Picture. In other words, beginner docs show you a set of tools, advanced docs show you their logical underpinnings, but intermediate docs would tell you how they work together, how to build something with them. Hence all the focus earlier on “large programs”.

(I then made a sword metaphor to highlight this difference.)

Without this kind of corpus, we create a sense that Rust is a language for toy programs, or for people who already know about program design from a different space. There’s no way to learn how to write big programs with Rust without just doing it yourself, and that can be a risk people are unwilling to take. Worse, several kinds of designs from other languages (especially those that lean heavily on object-oriented design) are downright painful in Rust, and without a written game plan for how to accommodate that it can be a tremendous stumbling block for people learning Rust.

If this all feels like a massive oversimplification, it probably is. This is mainly a summary of yesterday’s Twitter thread for my own purposes, so i can have that list of ideas that came out of it. If you have more specific ideas for documentation that could fill this space, let me know! I’d love to see some of this come together this year.