GTO docs

[aguschin]

Check out at https://mlem-ai-gto-docs-pzdfnkadkdwtv.herokuapp.com/doc/gto

close iterative/gto#293
First version of GTO docs.

[github-actions]

803e7cf

Link Check Report

• content/docs/gto/get-started.md
  • /doc/gto/command-reference/register = https://mlem-ai-gto-docs-pzdfnkadkdwtv.herokuapp.com/doc/gto/command-reference/register (404)
  • /doc/gto/command-reference/assign = https://mlem-ai-gto-docs-pzdfnkadkdwtv.herokuapp.com/doc/gto/command-reference/assign (404)

2/46 links failed.

[francesco086]

Perhaps my first question would be: why writing the gto docs as part of the mlem documentation?
From what I can tell, it's because it is necessary to build a model registry. Same goes for dvc, but dvc has its own documentation page.

Where am I going with this question? I guess the "why" you are writing this, is to enable users to build a full-featured model registry. This comes from the cross-use of 3 tools: mlem, dvc, gto.

If I am right, and this is the goal, then I would suggest to avoid trying to write a general introduction to gto here, that should be in its own documentation. Rather, write directly "how do I build a full-featured model registry using dvc, mlem, and gto?".

[aguschin]

Thanks @francesco086. This is good point of view. I'm opening a thread based on your comment to keep a discussion re it in a single place.

Minor: If you check out DVC docs, you'll see there are docs for Studio and DVClive. We can put this "GTO documentation" there or here (I used mlem.ai cause it was easier for me). Or to a separate website, like iterative.ai/doc maybe? Not sure. We need some place to keep GTO docs anyway.

Major: explaining how to build a registry with DVC+GTO+MLEM. Good question where to put that. In this PR you can see I was going to put answers in /doc/gto/user-guide. I guess the Tutorial format would be the best for this, and we could add it to each product involved under Use Cases (e.g. here it can be next or instead of "Pure MLEM Model registry"):

The other option is to create a GS with this - but that would be way to heavy for Get Started. I guess Tutorial or blog post serves the purpose better.

Another place to have this is Model Registry page in Studio docs. But, not sure yet how UI (Studio) and CLI (GTO+DVC+MLEM Tutorial) could co-exist here. Maybe cross-links are a better approach than having this in Studio docs.

Again, good topic to think about 🤔 We also leave CML out of the picture above, it also can be a part of a MR...

@tapadipti, have you had any discussion about setting up a DVC+GTO+MLEM Tutorial to complement Studio docs? Looks like it much needed, but I can't see we ever created something like that.

[jorgeorpinel]

I think it's a good place to put GTO docs if we want docs beyond a CMD/API ref (otherwise we could do with a README and possibly a site like https://docs.iterative.ai/dvc-task/reference/dvc_task/

Major: explaining how to build a registry with DVC+GTO+MLEM. Good question where to put that...
Tutorial format would be the best for this

We mention it very high-level in https://mlem.ai/doc/use-cases/model-registry now. And there's the https://iterative.ai/model-registry solution page separately. I'm not sure how much we want to go into the details of this 3-way integration. May be a good blog topic indeed. Let's create a separate issue to discuss that, though?

[tapadipti]

https://iterative.ai/model-registry should have links to all relevant docs pages. But since the docs can't reside there, Studio docs look like the next best place to me for explaining how to build a registry with DVC+GTO+MLEM. We could create a Use cases section. But depending on how much and what content we need, a blog post may also suffice. And docs specific to the GTO cli should definitely be separate.

If you check out DVC docs, you'll see there are docs for Studio and DVClive.

This is to be changed. We will host Studio docs separately in its own docs site (like CML) - although we don't have dates for this yet.

[aguschin]

Ok, so I'm trying to draft that blog post - please see https://www.notion.so/iterative/Tutorial-Model-Registry-in-Git-with-DVC-MLEM-and-GTO-af124368ce9f4523a568a7e1875c7af3 - high-level feedback would be appreciated.

[tapadipti]

Thanks @aguschin. I've left some comments in the draft blog post.

[jorgeorpinel]

close iterative/gto#293

Prob still need to update the README as well? 🙂 (no rush)

[jorgeorpinel]

you check out DVC docs, you'll see there are docs for Studio and DVClive

I think we should follow something similar to https://dvc.org/doc/dvclive here:

• Short docs home page (links to installation in README, for example);
• Get Started (single page);
• Technical reference (commands in the case of GTO)

Everything else may be overkill here. Please let's avoid the situation we have in MLEM in general with too many docs we can't properly finish 🙂

[jorgeorpinel]

Instead of a big User Guide, for now we can have a single guide page explaining these formats and their mechanics (again, similar to DVCLive's Folder Structure doc).

[aguschin]

Thanks for the all your feedback. We were releasing MLEM 0.3.0, so I was a bit off this. In general:

1. I processed your feedback - thanks! - feel free to bring more
2. Let's focus on GS, but I'll work on other things while I wait for you
3. Let's see if UG can fit a single page. Don't want to complicate things and write extra things, but it may be required to split in subpages.

[jorgeorpinel]

Get Started review 👇🏼 Let's focus on this first? In fact, splitting the PR would be ideal IMO.

[jorgeorpinel]

👍🏼 👍🏼 👍🏼

I kind of like that we start by showing the end-result! It's a good way to deliver the value proposition quickly in here (main purpose of this doc).

[jorgeorpinel]

This whole page is also not in sidebar.json (minor?)

[aguschin]

yes

[jorgeorpinel]

Still secretly published in https://mlem.ai/doc/gto/why-gto.

[jorgeorpinel]

Suggested change

	To create an Artifact Registry with GTO, you only need a Git repo and GTO
	package installed. There's no need to set up any services or databases, compared
	to many other Model Registry offerings.
	You'll need [Python](https://www.python.org/) to install GTO, and
	[Git](https://git-scm.com/) to use it.

[aguschin]

Not clear now why you need DB/Services at all - if we talk about GTO installation, let's remove all mentions of MR.

[jorgeorpinel]

I removed the part about DBs because it didn't seem too relevant to mention in the installation page, but it may make sense in other docs.

Not sure I understood your suggestion wrt MR mentions.

[jorgeorpinel]

A couple questions on whether we want to expose Git technicalities or not (apply to all docs, mainly cmd ref, but I'm only commenting on a couple pages).

UPDATE: Please ignore this for now...

• We can address later. There are lower hanging fruit here.

[jorgeorpinel]

Maybe we should be more specific on what it does, like:

Suggested change

	Create an artifact version to signify an important, published or released
	iteration.
	Create a Git tag containing the artifact's name and version.

Not sure, e.g. in DVC sometimes we keep it general (https://dvc.org/doc/command-reference/commit) and sometimes specific (https://dvc.org/doc/command-reference/checkout).

I guess it depends on whether we expect users to be familiar enough with Git and/or whether we want them to keep in mind the mechanics. But if we consider these implementation details, then let's keep it general but also remove/ hide Git tag details in general.

[aguschin]

Since the pages are auto-generated, this requires changing the code. Will do that later.

[jorgeorpinel]

If we're mainly concerned with CI/CD let's be specific instead of saying just "downstream"? More concrete

[jorgeorpinel]

Maybe we should dissolve THE relatively long intro (reusing some of the text in each section). That way we get to something actionable faster:

[jorgeorpinel]

Last batch of suggestions on Get Started:

merging the current docs to improve them later