"intermediate docs" planning

[QuietMisdreavus]

As part of https://github.com/rust-docs/team/issues/4, i'd like to start narrowing the possible ideas (or possible source better ones) for the "intermediate docs" goal. It's a fairly broad idea with a lot of possible applications, so i want to start trimming it down a little.

This is my earlier long-form discussion about this. Here's the key list from that (plus suggestions from farther discussion):

• Small-form idioms and large-form design patterns
  • The former can be kinda sourced from clippy, possibly other informal/totally-oral style guides in e.g. the compiler or servo
  • A possible inspiration from other languages includes the Go compiler's Code Review Guidelines, full of little tips
  • The latter can kinda start from https://github.com/rust-unofficial/patterns, but needs to be extended from lessons from e.g. the compiler, servo, production users
  • The book The Architecture of Open-Source Applications could also serve as an inspiration for broader design patterns, to say nothing about dedicated "design pattern books", as long as we can also give a good example of how the ones we describe do/don't apply to Rust
  • Possible idea: survey some set of popular crates (the playground set?), sort for the smaller ones and pick out ones that would make good demo cases
• Dark-corner language features
  • nomicon
  • The Little Book of Rust Macros
  • Rust FFI Omnibus
• Long-form guides of how to integrate large libraries (think tokio) into a larger application, or just for their general use
  • Something like a guided version of the cookbook?
• Focused "survey the field" guides around a given area, e.g. concurrency, embedded, etc
  • Could try to link up with the 2018 top-level working groups to source their work

What i'm looking for at this point, rather than strictly more ideas, is some kind of consensus as to what we should focus on. Much of this requires that we work with other teams or maintainers, so being able to focus that work (rather than trying to do everything all at once) would be helpful. For example, if we decide to create docs to help with the 2018 focus areas, then planting ourselves within those working groups early will help a lot in the long run. Likewise, focusing on idioms and design patterns may lead to talking to core and/or community teams to talk with major/production users to get a sense of the lessons they had to face on a more technical level.

If anyone wants to claim or assist a topic, please let us know!

[QuietMisdreavus]

Possibly relevant: The API Guidelines put together by the libs team.

[Havvy]

Does The Little Book of Rust Macros count as intermediate docs? If so, we may want to talk to Daniel Keep about just including it in the Rust bookshelf?

[steveklabnik]

I have historically wanted to do this, but it’s worth noting that Macros 2.0 is going to be stable this year. I’d want it updated to the new syntax; we should basically pretend macro_rules doesn’t exist IMHO.

On Feb 23, 2018, at 4:09 AM, Ryan Scheel notifications@github.com wrote:

Does The Little Book of Rust Macros count as intermediate docs? If so, we may want to talk to Daniel Keep about just including it in the Rust bookshelf?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[QuietMisdreavus]

I saw a couple movements from outside our team today that are relevant here:

First, from the futures-rs 0.2 announcement:

We are also working on a book, Asynchronous Programming in Rust, that will provide comprehensive explanations of the library and how to use it, including exercises and case studies.

Also, the Embedded WG is planning on putting together "The Embedded Rust Book", which is directly mentioned in one of the bullet points i listed above as a possible avenue.

[QuietMisdreavus]

Update: Asynchronous Programming in Rust has been started, and will get get filled in over time.

[QuietMisdreavus]

Another mini-book that could be developed and adopted is the Rust FFI Omnibus. Right now it's a collection of examples around various methods of bringing data across the FFI boundary, but if it were extended, it could adopt the FFI chapter from the nomicon. There have been several community blog posts about using Rust to extend various other languages, and it would be nice to bring those lessons into a sort of extended case study, if possible.

[QuietMisdreavus]

Also: In the announcement for the ecosystem working group, two goals announced were polishing and publishing both the API Guidelines and the Cookbook.

[obust]

Bringing back some ideas from the compiler-performance-wg thread https://internals.rust-lang.org/t/rust-compiler-performance-working-group/6934/32?u=obust

What book would answer the following topics:

• Reduce compilation time
• Reduce binary size
• Improve runtime
• How to structure large codebase

[QuietMisdreavus]

This collection of blog posts about idiomatic rust was also brought to my attention today.

[QuietMisdreavus]

@obust A discussion about "efficient rust" could be its own beast. Some parts could be integrated into a book of idomatic rust, but "hyper-optimizing" binary size is its own discussion. I'm reminded of this old post about rust binary size from a while back.

[frewsxcv]

Potentially related, I opened an issue on rust-lang/rust for expanding the bookshelf: https://github.com/rust-lang/rust/issues/49453 If that GitHub Issue / conversation should live in this repository, I'm fine moving it here

[steveklabnik]

@bstrie points out that @burntsushi's crates would be a good place to look for inspiration on structuring real projects

[frewsxcv]

in case it helps, brson has compiled a list of rust related blogs and resources:

https://github.com/brson/rust-anthology/blob/master/master-list.md

[QuietMisdreavus]

Notes from a session at the Rust All-Hands:

There's a presentation "A very brief introduction to Rust" that's a 20-slide presentation that they run through at Rustbridge that gives a really high-level overview to syntax.

An idea i had in the original Twitter thread was splitting the "idioms" docs into a smaller "phrasebook" and turning the bigger "design patterns" into a larger "field guide". This could be extended to provide little guides, like various "...in 10 Pages" guides, for things like lifetimes, modules, macros, etc.

[steveklabnik]

Ideas for a lifetime book https://users.rust-lang.org/t/isnt-rust-too-difficult-to-be-widely-adopted/6173/61