GS: reorg / rewrite

[jorgeorpinel]

Mainly from #43 (comment)
and feedback from @shcheklein

General points to address (may require partial or full rewrite):

• GS is very important. If a user didn't understand it, they won't use the tool.
• mlem init (copied from DVC) is not needed. GS is should showcase the happy path.
• Try combining the multiple current pages into 2 larger/more meaningful sections (similar to the 2 first sections of the MLEM release post), e.g.
  i. Capturing models (saving + packaging?)
  ii. Productionizing (applying, serving, deploying)
• 80% of important information should on the 1st screen in each page (or section?). The command we're explaining should be very visible.
• Remove if __name__ == "__main__": and other code for brevity.
  Code may be not reproducible if it's shorter: We may show full examples further down (scroll-to) or collapsible sections. Or nowhere (there's an example repo for this)
• iris dataset looks very toyish. Better to swap it with a more realistic dataset. Extracted to Use more realistic dataset in docs #198
• Summarize text, consolidate sections, etc. to make the content in general shorter, concise, and on point.
• Index page: Hide the info. about example repo tags (see Content for /docs #43 (comment)).
  • Remove all ⛳ Git tag sections throughout (repetitive git commit commands). Link to the tags where needed instead.

---

• Also address GS: more feedback #129 ?

[jorgeorpinel]

Hi. The checked boxes are currently being addressed in #129 right @mike0sv @aguschin ? Thanks

[aguschin]

The checked boxes are being addressed in #188.

Try combining the multiple current pages into 2 larger/more meaningful sections

Not doing this, don't think it's needed in the current structure. We'll address this (in the other way though) once we start working on #190

80% of important information should on the 1st screen in each page

Almost done, except for deploying page - but I'll update that one as well soon.

[aguschin]

Ok, the only thing left is applying some other dataset. I'm extracting this to another issue. #198

[jorgeorpinel]

Well, there's also

Try combining the multiple current pages into 2 larger/more meaningful sections... e.g.
i. Capturing models (saving + packaging?)
ii. Productionizing (applying, serving, deploying)

And in fact maybe we can have a single-page Get Started, based on the latest improvements (in #188).

Should we reopen and discuss that here, or create a new ticket?

[aguschin]

As I stated above, I don't think it's needed. Better to have it well-separated than squeeze everything onto one page IMO. As an option, I can try to use tabs for all 4 sections, and we can TAL how it can look like. But don't like it since the page will be huge. We have this ticket to try to have a single "easy config" page #190 - that sounds similar to what you want here, but it's a different thing and task.

[jorgeorpinel]

Yes but I discussed this with @shcheklein and we thought it would be worth it exploring that route (at some point, probably most interesting along with #198).

One way to put it is that "MLEM is not DVC", referring to the fact that we originally tried copying DVC docs structure and length including the Get Started, but really the main value of the tool can probably be delivered (main purpose of initiation-type docs) in a shorter form.

tabs for all 4 sections

No need to try this IMO -- it just moves the navigation from one place to another. I'm thinking of another GS rewrite, basically. May not be an immediate priority.

[aguschin]

Having hard time imagining how to squeeze everything in the current GS in one page. How do you see this GS then? Showing the save+deployment part only? Or what?

[jorgeorpinel]

Not sure, depends what's MLEM's core value proposition. Probably just focus on save (bootstrap) and deploy, and mention the other workflows (apply/serve/build) in passing, but move the content to longer guides.

But anyway, for now I'd recommend that we try to get the new GS merged: #188 (comment) seems a bit stuck.

[aguschin]

Probably just focus on save (bootstrap) and deploy, and mention the other workflows (apply/serve/build) in passing

This is Quick Start to me. It's what we have in README rn.

Yep, #188 will be merged soon. @madhur-tandon is working on it.

[aguschin]

Getting back to this issue with feedback from @omesser. If I got @omesser correctly, GS feels "disconnected". You open https://mlem.ai/doc/get-started, save the model, and then you can close it without using MLEM to apply/build/deploy models. So https://mlem.ai/doc/get-started page should have all those examples (?) or maybe some of them.

TBH, this looks like Quick Start for me, not like Get Started. In MLEM repo, we have this brief quick start https://github.com/iterative/mlem#usage. WDYT? @jorgeorpinel @omesser

[jorgeorpinel]

So https://mlem.ai/doc/get-started page should have all those examples (?)

This idea seems similar to the one check box still open above:

Try combining the multiple current pages into 2 larger/more meaningful sections

this looks like Quick Start* for me

If a "quick start" (one-pager) is enough, then why not? But if not, 2 is also better than 4.

*Definition-wise, to me Quick Start only hooks you but it's not complete: you need to go elsewhere to finish the story.