New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"intermediate docs" planning #8

Open
QuietMisdreavus opened this Issue Feb 21, 2018 · 15 comments

Comments

Projects
None yet
5 participants
@QuietMisdreavus
Member

QuietMisdreavus commented Feb 21, 2018

As part of #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
  • 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

This comment has been minimized.

Member

QuietMisdreavus commented Feb 22, 2018

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

@Havvy

This comment has been minimized.

Havvy commented Feb 23, 2018

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

This comment has been minimized.

Member

steveklabnik commented Feb 23, 2018

@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Feb 28, 2018

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

This comment has been minimized.

Member

QuietMisdreavus commented Mar 13, 2018

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

@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Mar 21, 2018

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

This comment has been minimized.

Member

QuietMisdreavus commented Mar 21, 2018

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

@obust

This comment has been minimized.

obust commented Mar 21, 2018

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 comment has been minimized.

Member

QuietMisdreavus commented Mar 21, 2018

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

@QuietMisdreavus

This comment has been minimized.

Member

QuietMisdreavus commented Mar 21, 2018

@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

This comment has been minimized.

Member

frewsxcv commented Mar 28, 2018

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

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 29, 2018

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

@frewsxcv

This comment has been minimized.

Member

frewsxcv commented Mar 29, 2018

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

This comment has been minimized.

Member

QuietMisdreavus commented Mar 29, 2018

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

This comment has been minimized.

Member

steveklabnik commented Apr 17, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment