Polish the Cookbook to 1.0

[KodrAus]

This is a tracking issue for polishing the Cookbook as a stable resource. We might want to close this in favour of an issue on the Cookbook repository.

What do we need to do before we can call the Cookbook '1.0'?

[KodrAus]

cc @aturon @withoutboats

[KodrAus]

@AndyGauge raised a good point about it not being really clear where we want to go with the Cookbook. Maybe we should reaffirm our broad vision for the Cookbook so we've got something to anchor the discussion around its reorganisation.

I've been wondering how the Cookbook relates to crates.io. We could theoretically improve support for surfacing library examples through crates.io and achieve something Cookbook-like through categories and the organisation of crates within them. That to me suggests the Cookbook as a separate resource should have some broader goal than just discovering libraries and how to use them. Maybe they should be tied together in some way?

So what do we think the Cookbook is? Where does it fit in the scheme of tools and resources we have for discovering libraries? Any thoughts?

[steveklabnik]

So, at the work week, the docs team was talking about our "intermediate resources" charge from the roadmap. We didn't like the "beginner, intermediate, advanced" framing very much, and after talking about it, realized we preferred:

• learning rust
• using rust
• mastering rust

This framing, for me, clarified the relationship between RBE and the cookbook: RBE is about learning Rust, but the cookbook is about using Rust.

Given that using external crates is such an important part of using Rust, it makes sense to me that we would talk about external crates, and often.

We could theoretically improve support for surfacing library examples through crates.io and achieve something Cookbook-like through categories and the organisation of crates within them.

I like this idea a lot, but I also think the perfect is the enemy of the good; I think we should ship the cookbook now, and if this kind of thing comes to pass, retire it in favor of such a system. But people need this kind of help now, rather than when we build some sort of perfect future, IMO.

[AndyGauge]

I like the framing of 'using rust' as the focus. The cookbook is code heavy and light on descriptions. Some recipes have no description or references (Read and Write Integers in Little Endian).

Does it make sense to draft a recipe standard, and bring all the existing recipes up to that standard, merge the outstanding new recipes and ship it?

Once we ship start the reorganization effort.

Edit: There is a standard, Contributing.md#example-guidelines. Should we bring existing recipes up to this guideline to call it 1.0?

Edit: I found this Issue that amends the style guidelines. rust-lang-nursery/rust-cookbook#302 I think it is pretty clear, and should probably be merged into CONTRIBUTING.md

[KodrAus]

I also think the perfect is the enemy of the good; I think we should ship the cookbook now

@steveklabnik I agree, it would be silly not to ship the cookbook we've got now, since it's already useful for people 👍 The learning, using, mastering framing also answers my question about where the Cookbook format fits with other resources.

Once we ship start the reorganization effort. ... Should we bring existing recipes up to this guideline to call it 1.0?

@AndyGauge This sounds like a good path to me. I think you've got a good idea of what needs to happen to get things moving, would you like contributing rights to the cookbook repo to be able to get started?

[AndyGauge]

I'd be happy to help out with the day to day operations, get the PR queue cleared, and write some code that gets us to 1.0.

[budziq]

@KodrAus @steveklabnik sorry for keeping radio silence for so long. Since my daughter was born 3 month ago 🍼 has taken all of my free time (and any left is used for precious shuteye). So unfortunately I will not be reliable as cookbook maintainer for some foreseeable future. I'll try look on the PR queue from time to time but I cannot guarantee anything 😞.

I'd really appreciate help from @AndyGauge!

[AndyGauge]

@budziq congrats on the dad gig! There's nothing that gives life meaning like raising children.

[KodrAus]

@budziq Absolutely no problem! Thanks for all your amazing effort on the Cookbook over the last year ❤️ Try get some sleep when you can!

[aturon]

@AndyGauge Great chatting about this today! I'm eager to provide support on this work, though I can't take on direct maintenance work.

Here's the sketch that @withoutboats and I developed last year. Just as you talked about, the proposed organization was based on the crates.io categorization. We also put some thought into what crates/what topics to cover for a 1.0.

I agree that for a 1.0 we need to revamp the organization, at the very least, but that other tooling aspects can probably be punted for the time being.

Feel free to ping me on the gitter to talk more about this!

[aturon]

Another link: some thoughts on the inclusion policy