Organization of ml5 examples

[tlsaeger]

Hey community,
I'm submitting this issue based on a discussion over on Discord with @joeyklee, @afogel and @shiffman. We talked about how we can make the examples on our page more appealing to new users and all in all more organised.

I'm suggesting a a few things here and did a bunch of mockups so we can discuss this more visually.

Reference Page

First up on the old page we have a lot of recurrences, every examples is there in most cases three times. Once for Vanilla JS once for p5.js and once for the web editor. In my proposal each example is displayed only once with a link to all three »platforms«.

We also talked about writing a short description for each example and adding an image of it in action. I mentioned on discord, that this could be done by our community. One advantage would also be, that we could show the many faces of our community. If they take pictures using one example.

I think we could also ditch the name of the model from the example on the page. It's the PoseNet page so here are the PoseNet examples, @joeyklee also talked about ditching the underscore and I'm pro that as well. Even though I haven't done it all the designs you see here, I was just lazy.

If we don't have a description or an image this new version would still be beneficial and is easily adapted to that.

I think the Neuroal Network Examples illustrate this in the best way, if we don't have a description and image and just rework this in the new design, it would save a lot space.

Examples Page

@afogel and @shiffman also talked about how to rework the page https://examples.ml5js.org/ I took inspiration off that and worked out a list focused design. That uses that description we made for the reference page. I also links to our reference page, so it is not that much of a dead end.

We might even be able to squeeze in the image:

What do you guys think? I have never worked with React only Vue so I might need some help when implementing this into our library.

✌️

[shiffman]

I love this! Thank you for these mockups they are terrific! (I'm actually working on a new design for the Coding Train website and this is giving me some ideas 😜)

[joeyklee]

Thanks so much @tlsaeger ! I really appreciate the mock ups.

I'm totally in support of your proposals here and think these would make a positive impact on the experience.

Examples listed on each page of the learn.ml5js.org

If I remember correctly, these are all rendered markdown pages using Docsify under the hood, so we might have to do something special to bring JS in that would allow us to create the styles you've mocked up. e.g. https://raw.githubusercontent.com/ml5js/ml5-library/main/docs/reference/bodypix.md

There might be some interesting plugin that could help us -- https://docsify.js.org/#/awesome?id=plugins -- but I'm not sure what is in there 🤔

Re: updating the examples page - https://examples.ml5js.org/

Here we have a lot more flexibility what we do! Whether we build out your mocked example cards here OR integrate @afogel's suggestion of the cool indexed table, we basically can do whatever we want. See:

• https://github.com/ml5js/ml5-library/blob/main/examples/index.html
• https://github.com/ml5js/ml5-library/blob/main/examples/assets/sketch.js#L45

The data that populates that examples.ml5js.org page is pulled from here -- https://github.com/ml5js/ml5-library/blob/main/examples/examples.json -- so any kind of data modeling we think about, we should apply to this. The examples.json file is generated by diving into each of the directories/subdirectories of the examples folder -- https://github.com/ml5js/ml5-library/blob/main/scripts/update-examples-json.js -- which explains why there so far hasn't been human friendly examples names and descriptions. The advantage of this is that it is easy to maintain -- we just run a script to keep things updates --, but the down side is that we'd have to figure out a way to include other metadata that could populate those human friendly elements like images, titles and summary etc.

Hope this helps!

[joeyklee]

For the sake of maintainability, I could also imagine removing the list of examples from each of the reference pages on learn.ml5js.org and replacing them with a link to our examples.ml5js.org to centralize things and help reduce the workload while we are figuring out how our sustainability plan 😂

[tlsaeger]

Thanks for the feedback @joeyklee.

Examples listed on each page of the learn.ml5js.org

I did not know that all the styling from our docs is just a theme 😄 thought we designed and made it ourself using css. I will take a look on how can apply a "custom" style to those pages. For my first proposal of that page I think we will not need to implement any JS, but I'm gonna check that out.

Re: updating the examples page

I will dig deeper into the structure in the coming days to figure out where we can add our meta data and maybe human friendly names as well.

I guess routing everything to the examples.ml5js.org is a good idea in terms of maintainability, but would be a step down for the users. If you just have a link in the reference and need to search in examples again. There might be a better way to do it. 😉 I will think about that as well.

I will have my master presentation on Wednesday, till than I need to but some work in the presentation. I hope to find time to work on this next weekend.

[lindapaiste]

The data that populates that examples.ml5js.org page is pulled from here -- https://github.com/ml5js/ml5-library/blob/main/examples/examples.json -- so any kind of data modeling we think about, we should apply to this. The examples.json file is generated by diving into each of the directories/subdirectories of the examples folder -- https://github.com/ml5js/ml5-library/blob/main/scripts/update-examples-json.js -- which explains why there so far hasn't been human friendly examples names and descriptions. The advantage of this is that it is easy to maintain -- we just run a script to keep things updates --, but the down side is that we'd have to figure out a way to include other metadata that could populate those human friendly elements like images, titles and summary etc.

Keeping in mind that the metadata would be the same for all implementations of an example, it might be easier to organize this if we separate the folders first by model and then by example. Right now we separate by javascript/p5js before anything else so we aren't keeping multiple implementations of the same model together.

Each example's folder could contain sub-folders for javascript and p5js and also contain a metadata.json file with the title, description, image, etc. Maybe we can even keep the image file in the same folder.

[lindapaiste]

I've been playing around with adding more structured data to the examples. We can assign a media type and a task and then render those in the UI with descriptive icons. There are other sorts of tags/filters we could potentially use such as "Interactive" "Game" "Quick Start" etc. Obviously the description and image is a lorem ipsum.

A few of those might not actually be used. Audio and video can go because all of our videos are webcam and all of our audios are microphone. I haven't categorized all of the NN examples but I suspect that predict is not needed because our prediction tasks can be described by something more specific like classify.

Work in progress:
https://codesandbox.io/s/ml5-examples-w-task-and-media-icons-pzrouc?file=/src/App.tsx

[horizenight]

Hello If this issue is still open. I would like to contribute .

[shiffman]

Development on ml5.js is restarting again this summer with a new partnership between NYU in NY and NYU Shanghai! I'm tagging in @MOQN here who will be leading design and development on the website!

[tlsaeger]

@horizenight first up thanks for bringing this up again. Cool that you'd like to participate. @shiffman i know I was super quiet lately, but if you restart the project I'd love to be involved as much as I can. So please let me know.