-
Notifications
You must be signed in to change notification settings - Fork 294
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
Reorganizing the cookbook #375
Comments
Two examples of these category skeletons that @aturon and I drafted together: Algorithms
Concurrency
|
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. |
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? |
@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. |
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. |
@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. |
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? |
@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 |
Sounds like a good idea. I hope adding / modifying categories on crates.io is not too difficult. |
@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):
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.
The text was updated successfully, but these errors were encountered: