Think more about search and navigation

[brson]

The organization of the book is just barely enough to be workable right now, but I hope we can do a lot more.

Today there is a single index, organized on three axes:

• "section" - each example is stuffed into a section, like "basics", "encoding", etc. This is mostly to accommodate the linear book format, so that it's readable front-to-back and has something of a 'narrative' organization
• crate - each example is badged by the crates they include. Those badges link to docs.rs
• category - each example is badged by the crates.io categories it belongs to. Those badges link to the category on crates.io

There are some issues with this:

• duplication of section and category - these are similar concepts but different. the categories are strictly tied to crates.io and examples may fit into multiple categories. sections on the other hand are organized to the needs of the book.
• defining sections - it's not easy to organize examples into sections, to decide what the appropriate sections are, and which one section to assign any example to
• categories' links are not obviously useful - maybe navigating to crates.io would help a user discover other interesting crates. not sure
• scaling - the cookbook is going to eventually be really big, and a single massive index will become unnavigable

And now some of my thoughts on how to deal with these:

I think for the sake of bookish organization it's important to try to split examples up into sections, try to make them progress in a somewhat narrative way - more fundamental things first, leading to higher-level tasks that build on the foundations, etc. The actual section naming and composition I'd expect to change based on experience and based on the actual examples we've got. We can also crib off of other such books. So for now I'm inclined to just live with the semantic duplication between book sections and categories.

But I also had an intent, that is not realized at all yet, to introduce filtering or searching, based off of the crate and category badges. The idea is to be able to narrow down the index based on what you are looking for, to make it more navigable. So e.g. click on the 'rand' crate badge and every example that does not contain 'rand' disappears; click on the 'net' category and every example that is not in the 'net' category disappears.

This obviously has the problem that the badges already link somewhere, and those destinations are useful - of course there should be a docs.rs link for every crate. So to accomplish this we would need some new visual / navigation concept. I don't have any great ideas right now.

One other thing, with the 'narrative' organization of the book, it might be good to have some sort of connecting text that ties section together. e.g. the "basics" section could start with an introductory text of some kind explaining what the section is about, and what's rusty about the topics to come. Haven't thought through that much.

[brson]

Another observation: it's impossible to Ctrl-F the index for a crate name because the badges are images.

[budziq]

cc #246

[jaroslaw-weber]

how about one example per file and then additional file with tags (comma separated )? we coule then generate a static page, one page per one tag. we would avoid duplicating files and would be able to have same code in multiple categories. Then we could generate one big index of all tags and navigate from there.
we could also list all crates used in cookbook and use that for navigation and reference.

[AndyGauge]

I have been pondering an overhaul and wanted to express my current line of thinking.

Categories

Remove the sections all together. Organize the cookbook with the same top level structure as Crates.io categories. Categories are sub-folders of the src directory. We could extend large categories with a few series. These would be sub-folders of the category.

Recipes

Recipes would be individual files, saved within a category named directory. The recipes can be copied and pasted from the current sections, and have the references added to the bottom. Recipes would begin with a number, for sorting purposes.

Summary and Table of Contents

In the src directory would be a main.rs file that creates the SUMMARY.md file and the Table of Contents. This generator would parse the directory format. The sort order of the categories and series would either be in a file, such as structure.json (or yaml or toml). The SUMMARY would have categories, and links to the individual recipes. The table of contents would be less busy.

Category Generation

The files served by mdbook would be created from the recipes, replaced into the src folder. Potentially leverage inotify for file changes in the generator. Have the generator launch mdbook serve.

Contributing

With these changes, individual recipes would be a single file. To insert a recipe above other recipes, rename the files.

The idea is to reduce the amount of effort for an individual contribution. We lose sections, and potentially crates on TOC, but they remain on the recipes. I'm not sure how much value crates on the table of contents would be if they were sorted by category. How many people are coming to the Cookbook looking how to do X with Y crate? I'd assume they'd be looking in Y's documentation instead. This also might be a moot point if the generator can parse the recipe to get the link, the title, and the badges. These things literally are line 1, line 4, and line 6.

[jaroslaw-weber]

@AndyGauge
i think its better to define category in meta file (json or toml). copying files to different categories will be problematic to update. you probably saw how I implemented it in my solution.

[AndyGauge]

Right now, I'm moving to an intermediate solution that puts the recipes into folders, and the book structure is just manually manipulated. I'm still hoping this will line up with the visual redesign you've got going--it looks great.