Reorganizing the cookbook

[withoutboats]

@aturon and I have been discussing the cookbook over the past few weeks. One of the main things we've talked about is organization and focus, to make it easy for users to find the recipes they're looking for.

An idea that I believe was @aturon's originally was to organize it along the same lines as crates.io categories, so that they can cross reference each other. The goal would be to grow toward a 1:1 correspondence between categories and sections in the cookbook (some categories may not be appropriate for sections, we'll see in the long term).

Additionally, we had some concern about the specificity of some recipes we have right now. We think recipe headers should be written in a way that emphasizes the main learning for the recipe, so that users can find the recipe that solves their problem. The recipe might, in fact, demonstrate how to do some concrete thing, but the header would not

For example, the recipe would be called "spawn a thread." Ideally, it would do a concretely useful thing with the thread it spawned, but the header wouldn't be "do X on a new thread," just "spawn a thread."

Steps to this reorganization (which can be partially parallelized):

• We need to finish the skeleton of the new organization for the cookbook.
• We need to mold the existing content into the new skeleton.
• We need to fill out the missing sections.

Probably the next step if people are enthusiastic about this direction is to create tracking issues for each category where the skeleton for that section can live.

[withoutboats]

Two examples of these category skeletons that @aturon and I drafted together:

Algorithms

• Generate random values
  • … for numeric types
  • … within a range
  • … with given distribution
  • … of a custom type
• Sort a vector (*mention sort_unstable)
  • … with a custom ordering
  • … with a custom key
• Generate a hash of a value (*mention alternative hashers)
  • … for a custom type

Concurrency

• Spawning OS threads (thread::spawn)
  • … and waiting for its result (join)
• Sharing data between threads
  • … shared ownership (Arc)
  • … sharing stack data (crossbeam)
  • … and allowing mutation (Mutex) (*reference non-std implementations)
  • … and passing messages (mpsc) (*reference non-std implementations)
• Data parallelism (rayon)
  • Iterating in parallel
    • for_each
    • reduce
  • Divide and conquer algorithms (rayon::join quicksort)
• *link to async section for futures or async IO

[aturon]

Another important aspect here, which is implicit in the example @withoutboats gave, is that we're envisioning a bit more nesting than we currently have. In particular, there are many examples that come with a bunch of interesting variants, like generating a random value. It seems good to have a "main" variant, and then list the major variations people are likely to want.

We have a fuller list of categories for the first cut of the cookbook, and have mapped most (but not all) of the existing material into those categories.

[AndyGauge]

Is this a task to tackle to support rust-lang-nursery/ecosystem-wg#5 ?

I'm not positive how much linking the cookbook has received from outside sources, but if we are going to break the current URLs, we should do it before releasing the first major version. I do think the navigation is the biggest challenge of the current cookbook.

I'd imagine that increasing the 'chapters' of the book would help in locating the content within the chapters. Is that what the nesting would do?

Is this issue ready for some preliminary work?

[budziq]

@withoutboats @aturon 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 😞.

Any help like @AndyGauge 's is super welcome.

[AndyGauge]

We are moving forward on this. For now I've added a Project to move the existing recipes into a new organizational structure. I'm going to experiment with creating folders with individual files for this structure. Once there's a process in place, I'll convert these into issues and solicit some support.

[aturon]

@budziq I so very much understand! I'm grateful for all the work you've already done on this project.

---

In case it's useful, @withoutboats and I sketched out a possible basic organization here.

[sandeep-datta]

Folks IMO the the "Basics" chapter can be split into sub-chapters with more cohesion e.g. file I/O, file system tasks, random numbers, process control, time and date, error handling, cryptography etc. Would you accept a PR for this?

[AndyGauge]

@sandeep-datta check out #404 at www.yetanother.site/rust-cookbook

We are moving from the existing sections to align with crates.io categories. This work is very close to complete, but feel free to offer criticisms on the PR #404

[sandeep-datta]

We are moving from the existing sections to align with crates.io categories.

Sounds like a good idea. I hope adding / modifying categories on crates.io is not too difficult.