Simplify get started - condensed

[omesser]

https://mlem-ai-simplify-get-st-rnmia5.herokuapp.com/doc/get-started

Here, I'll create an alternative where there is a single get-started scenario, but will use some alternative paths in this scenarios (so the user can choose).

Details:

• used tabs for alternative model prediction (python, cli)
• kept local model serving as a distinct stage (because it's "basic" and simple)
• used tabs for alternative production deployments (docker, heroku) - we can add kubernetes here IMO. But I will wait with this until a more high level discussion about the structure is done

More context: #228 (comment)

[omesser]

Hi @iterative/websites ! I would love your assistance in preparing this suggestion / use case
I would like to experiment with introducing alternative use-cases to the get-started scenario of mlem, similar to the "CML Use Cases" in cml.dev. Here, there's no need for a switcher (e.g. gh,gl,bb) just a one-level tab system which I would hopefully be able to embed and reuse 2-3 times in the get-started page.
It's totally fine if I would have to break the page down to multiple markdown pages or edit some ts code or similar (but would love some guidance here).
Currently the docs are "pure markdown" - meaning, I don't see an easy way for me to introduce this without changing the site's structure in addition to bringing-over/creating a tab component similar to JSONTabs in cmldev.

Can you please help me out with this - provide me some simple tab structure/component in this branch I can then use?
Would appreciate the help 🙏

[github-actions]

e390226

Link Check Report

There were no links to check!

[aguschin]

@omesser, if you would like to make something like this (from https://cml.dev/doc/cml-with-dvc):

Then you need to use something like

<toggle>
<tab title="GitHub">
...
</tab>
<tab title="GitHub">
...
</tab>
</toggle>

see this file as an example https://raw.githubusercontent.com/iterative/cml.dev/master/content/docs/cml-with-dvc.md

Curious to see how it will look like)

[yathomasi]

In addition to @aguschin suggestion of using tabs, I think we can also use <details> tag if tabs don't make sense.
Example: https://dvc.org/doc/user-guide/overview#comparison-with-related-technologies
Usage:

<details>

### Title

...
content
...
</details>

[omesser]

@omesser, if you would like to make something like this (from https://cml.dev/doc/cml-with-dvc):

Then you need to use something like

<toggle>
<tab title="GitHub">
...
</tab>
<tab title="GitHub">
...
</tab>
</toggle>

see this file as an example https://raw.githubusercontent.com/iterative/cml.dev/master/content/docs/cml-with-dvc.md

Curious to see how it will look like)

Thanks @aguschin - that toggle/tab system is exactly what I was looking for 🙏

In addition to @aguschin suggestion of using tabs, I think we can also use <details> tag if tabs don't make sense. Example: https://dvc.org/doc/user-guide/overview#comparison-with-related-technologies Usage:

<details>

### Title

...
content
...
</details>

Re<details> - thanks @yathomasi we're already using this quite extensively, was looking for tabs specifically!

[omesser]

@aguschin @mike0sv @jorgeorpinel - please take a look and compare this with

• what we have today
• Get Started updates #228 - env

Would like to get your thoughts

[mike0sv]

For me this feels like a lot of text for one page 😄 I mean that I'd probably cut a lot of extra explanations and leave just something like this "Here's how to do X: <toggle>different approaches</toggle>. It just works. Next, how to do Y...". I'll try to make a draft like this just to see how it looks

U: see #244

[aguschin]

Kinda agree with @mike0sv - the page is long and I was thinking to hide serve/build/deploy behind a single toggle (probably with deploy as page that we show by default).

But this reminds me of discussion we had in #190 (comment), TLDR, there I suggested something like:

I have [ CV | Table data | NLP ] task
...<the selected part is shown>...

I want to [ serve | build | deploy ] my model
...<the selected part is shown>...

And this ^ is a configuration page to my mind, not a GS. So if we unite serve/build/deploy behind a single toggle, I'd like not to get this configuration page, but get a Get Started.

As a suggestion: we can keep in mind that we'll have this configuration page in some future. How to write GS so it would complement, but not replace that page?

[mike0sv]

Have a look at #244 (env)
It's a lot messier that this but it showcases my point I guess

[aguschin]

I would like to experiment with introducing alternative use-cases to the get-started scenario of mlem, similar to the "CML Use Cases" in cml.dev. Here, there's no need for a switcher (e.g. gh,gl,bb) just a one-level tab system which I would hopefully be able to embed and reuse 2-3 times in the get-started page.

@yathomasi, is there a way to achieve something similar? Like nested toggles?

Tried this and it doesn't work:

<toggle>
<tab title="TAB">

tab content

<toggle>
<tab title="SUBTAB">

subtab content

</tab>
</toggle>

</tab>
</toggle>

[yathomasi]

@yathomasi, is there a way to achieve something similar? Like nested toggles?

It is available @aguschin. We have already started using nested tabs eg: https://dvc.org/doc/install/completion#what-shell-do-you-have. Also, the syntax is correct.

It looks like there is an issue with mlem.ai I will take a look.

[yathomasi]

I just checked with the exact code you have provided on the current branch and it seems to be working.
Can you try yarn clean and run it again? cc: @aguschin

[aguschin]

After a discussion with @mike0sv and @omesser we decided:

1. select this variant of GS instead of others (current with apply/build/serve/deploy; Get Started updates #228; Simplify get started very condenced #244)
2. @omesser will make another PR on top of this taking some changes from Simplify get started very condenced #244

[jorgeorpinel]

Minor? I would not use the term "tutorial". We don't really have any proper tutorials here (maybe in the company blog though). Tutorial: walkthrough solving specific/real-life problem.

[jorgeorpinel]

Sorry, late review but I hope still relevant since there seems to be a plan to follow up on this per

@omesser will make another PR on top of this taking some changes from #244

I turned #244 into a draft for now, BTW.

---

feels like a lot of text for one page...
hide serve/build/deploy behind a single toggle

Yep, not sure why this is called condensed when it adds back several things we had previously consciously removed (e.g. mlem serve and build), doubling the overall length. We also introduced significant more structure and the section titles are confusing (Deployment, then Serve, then Deploy again? But it's actually about building/packaging...). The GS should be straightforward. Again, we had already decided to leave some things out for this reason. I think we should be a bit more careful with GS changes (OK to discuss for some time) to avoid going in circles.

a way to achieve something similar? Like nested toggles?

Keep in mind this requires a lot of clicking so it's not ideal for this doc. Not even sure about the plain tabs TBH (GS should be linear ideally) -- but I guess it can be fine as long as the "happy path" is always visible in the first tabs.

[shcheklein]

@jorgeorpinel in this case tabs should work better I think (similar to GitHub/GitLab) in CML. MLEM is not DVC. Get started doesn't have to be same and/or complicated as in DVC. It is condensed since it's a single page vs multiple, less clicks and text overall I hope. Other things - yes, we should be clarifying and reviewing titles if that makes sense). Write your specific concerns somewhere please.

[jorgeorpinel]

I have lots of several specific concerns but since this review is late I decided to do a PR instead (didn't push it yet) ⏳

[jorgeorpinel]

Some more comments (questions with check boxes cc @aguschin @omesser) I'll addressi n #265 as well. Thanks

[jorgeorpinel]

Not seeing a batch operation here..? Is there a better term than "batch" here?

[omesser]

this is indeed batch scoring (using the model to infer on a concrete dataset). Maybe the confusion is because the "batchness" is not demonstrated clearly. the example uses a "batch" of a single vector, but the csv (or whatever format) file here can be of arbitrary size (multiple rows in the csv) and the apply command will run through the entire datasets provided and infer the model with it.

@aguschin - Maybe the example should be slightly modified to emphasize the above - just echoing another line should do it :D

[aguschin]

@jorgeorpinel will it fix your confusion? Or maybe you refered to something like --batch_size X param that will process data in chunks of len X? Like:

$ mlem apply models/rf new_data.csv \
    --method predict_proba \
    --import \
    --import-type "pandas[csv]" \
    --batch_size 1

[jorgeorpinel]

the example uses a "batch" of a single vector, but the csv... can be of arbitrary size

--batch_size 1

Can we make the example more realistic, so that the batch is actually a batch (a group of things) ? 🙂

But I'm getting the feeling that the batchness aspect is not important here, which agains brings me to suggest we rename this to something like Offline model scoring (Idk, need your input to find a good title). Otherwise term "batch" may be a distraction (in the title).

[omesser]

It's still very much a toy example (that's fine for the get-started imo) - but took a stab at it here - simple making the dataset not a single vector but 2 should get the idea across imo

[jorgeorpinel]

OK from this I get that it is important to stress the batchness. Having 2 lines instead of 1 sounds simple and good. Thanks

[jorgeorpinel]

I thought we had decided to leave this out of the GS? Focus on deployment (which is more relevant and includes serving).

[omesser]

I'm not aware of this - it depends how aggressively we want to cut length here. @aguschin - thoughts?

[aguschin]

I bet almost every user would run mlem serve multiple times for his model until he decides to do mlem deploy. So it's good that we introduce it here.

Also, off topic - maybe we need to mlem serve streamlit (see UG) in GS? It will have a nicer look I assume. (from the other hand streamlit is not that polished now, and we use it in every blog post anyway - so keeping fastapi for now may be a better option).

[jorgeorpinel]

Sounds good, we should keep it then.

maybe we need to mlem serve streamlit

Up to you.

[omesser]

I think fastapi works better for us - better adoption and swagger api spec are a great place to showcase a "by the book" RESTapi server

[jorgeorpinel]

Confusing structure... (see this section and its sub-sections)

[omesser]

Not sure I get what you mean here exactly - I totally see a room for confusion between serving and deploying. I think it might be a real confusion in MLEM's UX we need to think how to improve.
Is that what you mean? or something else? can you elaborate a bit?

[jorgeorpinel]

I've started addressing this in a follow-up PR. Here's some more context:#265 (review)

room for confusion between serving and deploying

Exactly. I'm not sure yet if it's something docs-specific or more of a product question (UX) indeed. But surely we can at least ameliorate the issue with good docs structure.

[omesser]

I think it's a real product UX question - cc @aguschin @mike0sv let's discuss this a bit, brainstorm if we can simplify or communicate this differently - I get the confusion @jorgeorpinel has here 💯 .

For now I've built this and the next proposed iteration of get-started taking the current abstraction/structure as given (deployment builds on top serving) since the actual code is structured around this concept

[jorgeorpinel]

Nice, thanks. We may have conflicts among PRs though... I'll focus on finishing mine first.

[jorgeorpinel]

Please see #265 for some more concerns and follow-ups.