Overhaul visual design

[brson]

The current design is basically the result of a single pass back when there were only a few examples, and clearly isn't scalable. It needs a complete rethink. Some requirements

• Should be searchable my crate
• Should be searchable by topic
• CTL-F should probably work for crate names, where today they are graphic badges
• Continuing to use mdbook is preferable
• Should be a static site

Also see this issue about search and navigation for more thoughts about that subject.

[Phaiax]

You mean static site from the server side or from the client site (no javascript required/preferred)?

[budziq]

The site is generated via mdbook into a set of static html/js/css files served via github gh-pages without any backend (probably not requiring a backend would be the nicest aspect of the project to maintain).

And 99% of the styling and js comes directly from mdbook (with some additional features and fixes around the corner with upcoming mdbook 0.1.0)

Most likely we will be sticking with mdbook for now unless a better alternative comes into view.
The idea here is to solicit help from people with UX / webdev experience as current presentation is both rough and not really that user friendly. Not having any UX and webdev guys on board is currently the biggest cookbook problem.

Some ideas might be implemented directly in mdbook as we are on good terms with that project (I'm comaintainig it) and rest would be easily implemented in cookbook.

For instance in mdbook we were thinking about utilizing https://lunrjs.com for search.

[Phaiax]

One step towards Ctrl+F compatability of crate names could be to use <crate>regex</crate> instead of the definition with [![rand-badge]][rand]. Some javascript could get the version info by using the json API and replace the <crate> tag by some css that renders into a badge. The badge would look almost the same but with selectable text.

[budziq]

nice idea. on the other hand shields.io and our cache supports json output which contains the version number so js might process it in one go

[Phaiax]

which cache? the browser cache?

[budziq]

which cache? the browser cache?

https://badge-cache.kominick.com

we use caching proxy for shields.io due to its historic bad performance

[jaroslaw-weber]

I think we could split those long files into smaller ones with one example per file. If mdbooks supports subcategories with folders it would be easily maintainable (one folder one category, multiple files per category) I haven't worked with mdbooks but if we could do that we could make expendable menu, when clicking on category, with some js magic. Maybe not best solution but better than endless scrolling we have now. Something like rust book menu but expanding and hiding when clicking on category.
Also I think we could try different template for main page to make it nicer.

[jaroslaw-weber]

copypasted from chat discussion:

current ui/ux could be little more polished. personally i dont like the grey table header. also I think homepage could be little smaller ( show only titles and expand/move to category page on click) so we can see all the categories when we start a page. I would also move an contribution part to the bottom, and write very simple and short explanation what is the cookbook. https://repl.it/languages <- this looks much cleaner. I would also suggest go with something like bulma which is lightweight enough but helps with styling a lot. I could make an example UI if you are interested and we could vote/discuss it.

[jaroslaw-weber]

Brainstorming design, playing with different ideas. Ignore weird cyan color, it would be replaced with rusty color.
https://photos.app.goo.gl/NwLDD8jmsRV35k432

Edit: How about changing from mdbook to static site generator?
Something like this:
https://github.com/cobalt-org/cobalt.rs

[budziq]

First of all, thanks for taking this up @jaroslaw-weber !

https://photos.app.goo.gl/NwLDD8jmsRV35k432

Looks really nice! I wonder how this scheme would look on mobile browser (currently we try to support both phones and tablets)

I think we could split those long files into smaller ones with one example per file.

I also think that one example per page might be a more natural fit. Currently dumping all of the example names into main page and grouping examples is a crutch for the lack of search #167 (ideally we would have a full tech search with category/tag support)

we could make expendable menu ... Something like rust book menu but expanding and hiding when clicking on category

Rust book is implemented in mdBook so it is perfectly doable. mdBook sidebar supports nested chapters, making these collapsible would require some implementation (there is a stale issue about it in mdbook)

personally i dont like the grey table header.

It's one stylus/css edit away ;) we have never really had anyone with ui/ux background on board so most of the work is done on our best effort basis. Any suggestions welcome!

I would also suggest go with something like bulma which is lightweight enough but helps with styling a lot.

I'm game for any suggestions, I just wonder how bulma would integrate with mdbook and it's selectable colors-chemes

How about changing from mdbook to static site generator?

For now mdbook is somewhat a community standard for rust documentation (RBE, Rust Book, unstable book, rustnomicon, and few others.) making these uniform and giving a hint of coherence. Also we get playground and pdf export for free. So I would be hesitant to change it at the moment. But The cookbook would be quite unique in its purpose so trying to conform to the styling of other docs is most likely a bad idea so I'm game to any suggestions!

[jaroslaw-weber]

@budziq
thanks for comments!

Looks really nice! I wonder how this scheme would look on mobile browser (currently we try to support both phones and tablets)

Bulma is resposive so should look nice. I will send screenshots/html files later (tommorow maybe?).

I also think that one example per page might be a more natural fit. Currently dumping all of the example names into main page and grouping examples is a crutch for the lack of search #167 (ideally we would have a full tech search with category/tag support)

Ctrl+f is not an obvious idea for search, we could do table of content for this (as a different/last page), but I would not use it as a main page (cause its ugly hack).

I'm game for any suggestions, I just wonder how bulma would integrate with mdbook and it's selectable colors-chemes

Looks like mdbook is using one template for all pages. It may be a problem if we want to change main page. We could go with some hack.

For now mdbook is somewhat a community standard for rust documentation (RBE, Rust Book, unstable book, rustnomicon, and few others.) making these uniform and giving a hint of coherence. Also we get playground and pdf export for free. So I would be hesitant to change it at the moment. But The cookbook would be quite unique in its purpose so trying to conform to the styling of other docs is most likely a bad idea so I'm game to any suggestions!

Well it would be nice to have everything uniform. Although I thought of refreshing current style with something new, I could think about few ideas for improving the current experience as a compromise.

Rust book is implemented in mdBook so it is perfectly doable. mdBook sidebar supports nested chapters, making these collapsible would require some implementation (there is a stale issue about it in mdbook)

Actually I changed my mind with expanding 😆 . I think category page with links would be better idea.

I am planning to provide some layout, but would appreciate help with matching it with mdbooks/page generator.

[budziq]

Ctrl+f is not an obvious idea for search,

I also think that the biggest problem in cookbook ux is the main page and reliance on ctrl+f. I'd love to add lunr.js based search
the problem with lunr.js is its reliance on node.js for offline search index generation which would be a nogo (ideally the search index would be built along with the site without additional dependencies). But there does not seam to be any design doc specifying the search index

[jaroslaw-weber]

Initial design
https://photos.app.goo.gl/R8oKjpv3gHhDUizT2
instead of long category page i left just buttons with links. each example is on a single page. main page would be more like rocket page, just few links. more button would lead to "about page" which would have menu on the left so we would navigate from there. it will reduce scrolling.
for easier search we couns add a search bar in menu which would just redirect to google search with site: prefix. it would allow to search also by content.

is it possible to make it with mdbook? maybe partially.
we could also generate page with custom script using handlebars. we could even parse .md files and replace them with custom html. it would be more flexible but we would need to write the generating script.

[jaroslaw-weber]

the design would be of course responsive, and left menu would be hidden by default (similar to current solution)

[budziq]

which would just redirect to google search with site: prefix.

I would say that I would be very hesitant to add rely on any 3'rd party search engine. Stealing the rustdoc's search code (both rust and js parts into mdbook) might be a good idea

is it possible to make it with mdbook... we could even parse .md files and replace them with custom html.

To some extent, but it might require some customization on mdBook part (both styling and hooking to its parsing/generation without need for separate scripts).

In regard to the design itself, I find it and the single page per example little distracting / unfocused compared to current one (but I might be more than a little biased. I would need more opinions). On the other hand I really like the style of rocket's landing page and guide

[jaroslaw-weber]

Hey, thanks for feedback! We definitely need more people here!

Well the rocket guide has shorter examples so it is easier to put everything on one page (not so much scrolling). cookbook examples are longer. If you think one example per page is not a good idea we could leave it as it is (about 10 examples per page) or I could try to make fast prototype so you could test it.

i will check the styling in rocket page in more detail later maybe it will give me some ideas.

I will aslo try to start with polishish current style and make it work with mdbooks so we don"t have to change infra too much.

PS: Experimented a little with generating pages only with handlebars, as an alternative to mdbook. It is more flexible but would need implementing printing pdf, playgroud and code styling. You can check it out here:
https://github.com/jaroslaw-weber/cookbook-new-design

[jaroslaw-weber]

Hey again.
So I looked at mdbook template and styling files but it is not very flexible. Whole menu is generated inside mdbook script, content is also passed as whole block, so it is impossible to change it only with changing template. For changing styling it would require rewriting parts of css and writing some javascript for changing tag styles.

I created site generator which uses json and text files to generate website only with handlebars. You can check it out with link from the previous post.
So what it is doing is parsing folder structure and simple data and generate a website. Generator and parser are standalone so you can change the form of the website using same data. It is more flexible and clean solution than mdbook in my opinion. Printing pdf would be just generating everything on one website and the using html to pdf converter.
So, I implemented basic functionality, you can clone the repo and test it.
I also tested it and felt that one example per page is better idea but it is possible to change it by messing a little with generator file.
I also changed styling a little. I uploaded screenshots on my repo.
Is it an option to use static site generator instead of mdbook, if I make playground-like functionality and pdf print working?
I also added MIT licence to repo so other people can freely use it.

[aturon]

@jaroslaw-weber Thanks so much for the work you've put into this so far -- I think there are a lot of very promising ideas here! Here are some of my immediate thoughts.

• I find that the sketched design is exciting and appealing; overall this feels like a good direction to continue exploring!

• I don't think we need to be tied to mdBook, and I think that there are a lot of aspects of the cookbook that would benefit from a more custom design. For example, the home page you've sketched is very inviting, in a way that would be hard for mdBook to accomplish.

• I have mixed feelings, though, about not using markdown as the format for writing the content. I think even just supporting a small subset of markdown (e.g., codeblocks, links) would be fine.

• I personally think that one-example-per-page is a good move. To me, this helps focus your attention on the single snippet of code you're actually trying to grasp. And I think that, for the most part, you're going to be using the cookbook to look up how to do one specific task, and not want to be distracted by tons of other content.

  • We might be able to balance this a bit by providing some links to "nearby" content, e.g. related examples.

I have some more specific thoughts about the details of the visual design -- not sure if we're to the point where you'd want that feedback yet, though?

[aturon]

Oh, and I should say that I think search is critical and ideally would be done purely within the site. I imagine we could ship down a json blob with all of the recipe titles, for example, and just search that client-side (much like how rustdoc search works today).

EDIT: I see now this is tracked under a separate issue.

[budziq]

@jaroslaw-weber Thanks for all the hard work! The design certainly looks more approachable than the current one.

that would be hard for mdBook to accomplish

I'm not sure if I'd drop mdBook just yet. At its core it is just a static site generator which can be heavily customized. For instance, having separate template file for a landing page could certainly be implemented. But if we decide to switch the static site generator I would certainly would not like to write something like that from scratch ;)

Anyhow I might be more than biased here as I've became mdbook co-maintainer due to regular contributions related to cookbook requirements ;)

much like how rustdoc search works today

Yep, that's the idea. Although Steve has mentioned that homegrown search implementation in current rustdoc is hacky not reusable and not a viable way forward (shame)

[jaroslaw-weber]

thanks for comments! it is much easier to work with feedback.

@aturon we can use markdown for code blocks with custom generator. ill try to implement it later. if you look at the repo, i use [code][/code] and [snippet] as custom tags. i think its cleaner than markdown but we could alsot try markdown.
using markdown would be great for eventual moving from mdbook if we decide to do so.
we could balance it with related content but how would we decide what is related?
i will also try to work on search. just like you said, we could dump everything to json, but i wouldnt allow search from any page because dumping everything on every page would be heavy. maybe just dedicated search page?
feel free to comment visual aspects too, it will be great to get some suggestions.

@budziq well, i implemented most of the current functionality so i think i will be able to do the rest. but i understand your concern.
the problem with mdbook is that it generated some parts of html directly inside the rust and not using templates for everything. this prevents from adding custom classes in elements of html (it is probably possiblr with jquery but would be hacky). it is also difficult to write additional functionality. it may be possible to overwrite current css classes, but it wouldn't be very flexible, we would probably need to stay with current layout. im not saying we should ditch mdbook, it is just easier for me to write custom site generator than fight current styling. even if we decide not to use custom generator, it is easier for prototyping, we could use some ideas with mdbook.

local search with static website will be always little hacky.

[jaroslaw-weber]

im not giving up on mdbook yet, but its not trivial so need to think about it more

[Phaiax]

Hey @jaroslaw-weber and the others. After reading this thread and looking at md book I want to give some thoughts.

• In the new design, the vertical screen space per example increases because of the Crates and Tags sections. This increases the need for scrolling when I look at one single example. I like that most (80%) of the current cookbook examples fit into my browser viewport. The scrolling between examples is not so annoying, but making one example per page is a good idea, especially for googleability.

• I think we need some kind of user story that fits to with the design story. What is the question the user has in mind when accessing the cookbook? (-> How will he navigate with his knowledge? How can we help with navigating? How can we communicate that his problem is not covered by the cookbook if it is not? ). Where does he come from? (Google, Link to specific example in stackoverflow / discussion). What expectations does he have?

  • I also think (aka guess) that a not so small amount of the visitors is just browsing with the intention to explore and not with a specific problem

• I can devote some of my time to bring the search engine into mdbook if @budziq thinks that is a good Idea. (and if we decide to stay with mdbook)

[budziq]

@Phaiax Thanks a lot for the input. You raise very important points!

During this week we have had some discussions with @steveklabnik @aturon and @KodrAus (big thanks for the help and support!). One thing is certain that we need to catalog all the bits and pieces of the rust documentation story and come up with a strong vision so these will fall into place and reinforce each other.

I agree that I would like to be able to balance the usability and searchability of the cookbook with it being a resource that one can explore and shop for ideas.

In regard to search, the problem is actually twofold.

• offline content indexing which could be written in rust (possibly as a separate crate)
• the actual search in JS

And I would be super excited for you to contribute in either of these tasks!

Please note that even if we'll not decide to stick with mdbook in cookbook, it would still be used in all the other places https://github.com/azerupi/mdBook/issues/51 (RBE, nomicon. rust-book, etc) so it would be super desirable!
Such effort could be also reused within the RustDoc redoux.

[jaroslaw-weber]

Hey, small update (new screenshots). Made crates and tags little smaller, using crates.io tags as categories, also added code buttons (not working yet, just trying to decide on desing). Feel free to comment.

I also noticed that comparing to rocket.rs the design is little boring - there are only three colors (rusty, white and black). I will try some different colors later. I am leaving old screenshots just in case.
I am also thinking about code buttons and tags placement, probably will change them later.

https://github.com/jaroslaw-weber/cookbook-new-design
@Phaiax thanks for feedback! I changed the crates and tags section and made it smaller! I had it bigger because I was planning to use it as actual buttons but maybe it was too big.
Actually I have few pointers to current design (mdbook) related to this issue.
Crates/tags in current mdbook doesnt look like buttons, which may lead to people ignoring the functionality. Also I didnt know that you can click on "code" parts like File or HashMap (I didnt know they are linked). Maybe we could add some short explanation/tutorial about different functions implemented? For example

you can compile code and see the resullt! just click on the arrow (image here). to copy click on copy icon (image here). you can also find links inside recipe descriptions, for example try click on this -> File.

Also I think compile/copy buttons are too small on mobile.

To summarize, maybe we need tutorial page? Also search script is transferable so I think it is worth to start implementing it for the current version.

[KodrAus]

This is a fantastic effort @jaroslaw-weber! I'm really excited to see the cookbook getting a good UI/UX overhaul.

I only want to leave a little bit of feedback so you've got a chance to work through your own vision. Right now I think it's a bit tricky to get context as you navigate through the home page and collections of examples. I think this is mostly because we don't have a search bar and the sections aren't populated with a lot of examples. So I suspect this isn't really useful feedback right now, but wanted to put it out there.

Thanks for taking this on! I appreciate it's a lot of effort 💯

[dumindu]

Hi Guys,
would like to add two suggestions.

01. Two column layout

I don't know you already selected a final design for Rust Cookbook, but I would like to suggest to use a 2 column layout like on GitBook API Theme

About a year ago I suggested the same on Reddit Suggestion: Rust by practice/ Practicing Rust and on Github rust-by-example-Suggestion to use GitBook API Theme but that was not the right time.

However I don't know we have any plugin system on mdbook like on Gitbook and the constrains on UX on mobile.

A sample I created about a year ago

02. Make more newcomer friendly

Please make the cookbook more newcomers friendly instead targeting experienced systems programmers like on Rust doc 01. And please give basic to advanced examples to cover more.

ex. instead using only this example for std read line, how if we use a list like on this with the recommendations when we have to use each.

we should have one page like this for a single topic on each std lib crate

---

Thanks and Keep up the great work!

[jaroslaw-weber]

I should probably post it in navigation thread
#167
but I will post it here cause it may be related to the design I was working on.
So I have few points:

• we may consider switch to navigate menu with crates. i felt navigation by crate was more natural.
• we could make a big grid-style page for crates with all crates listed with links to crate page and very short description and maybe an icon. it would be great for people who starts but are not familiar with crates
• we could make page with ranking of snippets with most popular/useful on top.
• when I browsed category I saw lot of similar examples. we should give some opportunity to filter through snippets without "additional examples". too much of one crate is creating a "noise". but I am not sure about the solution. navigation menu with crates would solve this problem a little
• what is the cookbook purpose? why should I use it? who is the target? we should try add a questionaire to the current cookbook to gather opinions and suggestions! not everyone is looking at github. we need more feedback
• what color scheme should we use? should we go rusty or more original? (green, red etc)
• should we personalize cookbook? we could add something like "i already know this recipe" for hiding some stuff with javascript. do we need this?
• should we add tutorials for complete rust beginners? like explaining very basics, go "rust by example"-way?

I also added few features since last time:

• connected to crates.io
• expanded index.html (added "how to navigate" section)
• implemented compiling in browser
• implemented two types of search (one faster - search by title, one slower - search by content)

https://jaroslaw-weber.github.io/cookbook-new-design/generated/index.html

[budziq]

Transcription from gitter:

@jaroslaw-weber

why navigation is more difficult

• hmm I guess that the only major problem is lack of left/right button navigation between pages and keyboard navigation in general (I find it very convenient on mdBook). This might be tricky in case we have some filtered categories (got to next example in given filter? got to next category on last example?)
• I would suggest for search bar to always be present (but possibly minimized into an icon or a very short bar on the side pane)
• one page recipes are very fine idea, I'm just thinking about how we should approach recipes that are organized in a logical flow (take csv for example) each example would build on its predecessors. Should these be linked in any special way?
• I feel that the snippet buttons should belon on (or very near) the snippet itself

how is the work on search going?

It is highly experimental work in progress @Phaiax has made a POC https://phaiax.github.io/mdBook/cli/init.html?search=init
The search feature implemented in a sane way is highly desired feature for nearly all of the rust docs (rustdoc/ RBE/TRPL/Cookbook/Nomicon/ others) we track the progress here azerupi/mdBook#51

If anyone is willing to lend a hand there especially in rust index generation code by @olivernn https://github.com/olivernn/lunr.rs feel free to jump in (it might require some NLP domain knowledge, but refactoring work is also available)!

i have an idea, how about we xhange default navigation categories to crates?

We have discussed with @aturon about it. The current consensus is that the beast approach would be to follow crates.io categories (possibly keywords too) and secondarily the used crates names. We are thinking on making the cookbook something along the lines of "extended standard library companion book"
and it might require for cookbook to follow rust-by-example and crates.io more closely

[budziq]

@dumindu thanks for the suggestions. Please feel free to join in on the ux discussion anytime. We certainly need more eyes on the matter (I for one have no knowledge about UX design except for some opinionated gut feelings 😉 ).

And no. The UX/UI design is still very much under discussion and we might go with few more discussions before anything is decided (cookbook has a long way before it is matured on the level of RBE)

Make more newcomer friendly

This is a really tricky one indeed! Because in terms of std, we have both TRPL, RBE and the official docs. TRPL and RBE are providing a narrative that by definition cannot be put into the rustdoc, and these try to cover std. Cookbook was originally meant as a "crate cookbook" but general problem/solution approach need not be limited.
We already have few cookbook examples that are std only.
Moreover. We have two wishlist issues that are aimed to gather example ideas not related to libz-blitz crates (unfortunately these see very little traffic)

• Miscellaneous cookbook ideas #24 - misc/other crates ideas
• Cookbook ideas for std #266 - std ideas

[jaroslaw-weber]

copied from gitter
@budziq thanks for feedback.
few points:

• how should we approach recipies which has order? we could define order in json, add link to "before reading this we recommend reading x", add "read next" link, or filter secondary recipies from categories. we could also add order to links so we have "go next to this recipe" and statically check and generate list of some kind of ordering.

• we could also add "secondary or primary" flag and make it visually visible (different color?)

• to be honest i didnt use keyboard and go left/right feature a lot so i didnt find it useful, but if we go with more flexible design, the order may be hard to decide and confusing. good point

• ui is not decided yet, we are trying ideas so any feedback is welcomed

[jaroslaw-weber]

also, if we want to get people to get casually hooked from google search we may need to consider make snippets standalone as person entering from direct link didnt see previous recipies

[budziq]

As discussed on reddit we might be interested in:

• making the snippet buttons more discoverable
• adding some form of cargo.toml preview for given snippet (button with poppup? markdown collapsible content?)

[madkeen]

Hey guys, I would like to contribute my research/design skills to improving the the website. Is this a suitable place for this conversation?

I have a growing interest in open-source - keen to see how the design world can benefit from it's awesomeness. But also very keen to see what Rust is capable of in the next 'internet wave', and how it can make peoples experience of technology better: more accessible and more delightful.

[budziq]

Hi @madkeen,

I would like to contribute my research/design skills to improving the the website.

👍 All contributions are greatly appreciated

Is this a suitable place for this conversation?

Sure it is!

[renahlee]

Is this still being worked on? I'm looking for open source opportunities to contribute to and would love to learn about the visual design needs for the cookbook.

[AndyGauge]

@renahlee I'd love to hear some ideas. This particular issue appears to have stalled, but it is definately an open item.