Model registry docs consolidation

[dberenbaum]

This is an attempt to rework the docs in response to feedback that it's confusing and makes it hard to get started with our tools. I started with model registry because it's more limited than trying to redo experiments or data management.

The goal is to address a few different issues:

• Improve MR onboarding
• Try out a style more like a quickstart
• Consolidate docs across products
• Reduce duplication

The PR drops the two model registry overview pages in the Studio docs:

• https://dvc.org/doc/studio/model-registry
• https://dvc.org/doc/studio/user-guide/model-registry

The content was integrated into other pages (often it was already in other pages). The idea is to have high-level docs in one place and product-specific docs only for detailed guides/reference.

[github-actions]

Link Check Report

There were no links to check!

[dberenbaum]

Added a new page here to:

1. Consolidate info from https://dvc.org/doc/start/model-management/model-registry and https://dvc.org/doc/studio/model-registry
2. Make the first page less intimidating/quicker by focusing only on what's needed to add a model

[dberenbaum]

Include Jelle's recent video for people who don't want to read docs

[dberenbaum]

Add link to public model registry for those who just want to see what it looks like (taken from https://dvc.org/doc/studio/user-guide/model-registry)

[dberenbaum]

Moved this info to its own page

[dberenbaum]

Tries to cut down intro here to get to showing the Studio UI ASAP

[dberenbaum]

The rest of the changes on this page are just moving existing content around to fit the new structure

[dberenbaum]

@yathomasi Heroku is throwing an error:

 !     Compiled slug size: 1.4G is too large (max is 500M).
 !     See: http://devcenter.heroku.com/articles/slug-size
 !     Push failed

Any ideas how to fix it? Can adding static files to the static repo (see #4837) help?

[yathomasi]

Any ideas how to fix it?

I see it didn't run the gatsby build command at all so ended with huge size of node modules and cache.

I have retriggered the build manually and hope it will be fixed. ICYMI: there is a Manual deploy section in Deploy tab

UPD: Deployed successfully.

[tapadipti]

@dberenbaum If we remove this page, I think we should also remove the Experiments page which is at the same level. But the reason we recently added these pages is to make it easier for Studio users to find the core features of Studio. I think that we should work to consolidate the Get Started -> Model Management docs with the Model Registry user guide so that there's one source of the model registry guide. And then this page can serve as just a pointer to the guide.

[dberenbaum]

Yes! That's exactly what this PR does. See the changes to the redirects, which redirects this page to the guide. So it will still show up in the sidebar for now, since it was too much to also get rid of the Experiments page at the same time, but clicking on it will go straight to the guide.

Re: consolidation, the idea with this PR is that model registry docs are in 3 places (and link between each other where appropriate):

1. Use case - overview, why a MR, why ours
2. Get started - quick intro to learn how to use MR
3. Studio guide - in-depth info

[tapadipti]

Oh, I see the issue. You added a redirect to a page that you deleted (/doc/studio/user-guide/model-registry). So that link broke when I was running this locally and I thought you meant to delete that link altogether. With your changes, the guide now starts at /doc/studio/user-guide/model-registry/add-a-model. Not sure if that is the right page for this link. May be we should link it to /doc/use-cases/model-registry? But even that is not the right page, coz this is supposed to be a quick start guide.

[tapadipti]

Corrected the link here (redirected to the add a model page).

[dberenbaum]

Thanks Tapa!

May be we should link it to /doc/use-cases/model-registry? But even that is not the right page, coz this is supposed to be a quick start guide.

We could link to the get started doc, but I also think ultimately the goal is to drop /doc/studio/model-registry once we can also drop /doc/studio/experiments, so not a major concern to me.

[tibor-mach]

• Use case - overview, why a MR, why ours
• Get started - quick intro to learn how to use MR
• Studio guide - in-depth info

I still need to have a proper look at the changes but I really like this structure, in fact this is how I think all of the docs should be organised (and a fourth part which is just the API documentation). This is what Django uses, there was a great talk about this structure from one of its founders (but I cannot find it now).

And the Get Started stuff should be extremely prominent, right at the first page of the docs, the first thing you see (it also goes back to what we talked about on Thursday)

Personally, I would like to see Studio included in the docs more prominently, kind of the way I tried to do it with the Get Started guide on MR. Studio should be a first class citizen I think. You should still be able to see how to do the same stuff with FOSS but Studio should be the first one we show. And then specific Studio guides would be there only for the stuff not relevant otherwise (like setting up Studio, managing user permissions etc).

[tibor-mach]

And I would try to make this structure as explicit as possible. For example with Studio it really is not all that clear. The Get Started guide are really not in Studio documentation itself, but in the DVC documentation.

The Use case part is also detached.

Maybe even removing a specific subpage for Studio and integrating it into the rest (and dividing that explicitly into these four parts) might be the best. This way it is also easier to maintain it and avoid duplicates between Studio docs and the rest.

[tibor-mach]

If I open the documentation of Djanjgo, the first thing I see are links to the get started guides - the tutorial for complete beginners and then more advanced tutorials. The second thing you see are links to where to ask questions about the framework. And then some info about how the docs are structured so everyone can figure that out quickly.

I would just straight out copy this structure (just with more bling)

[dberenbaum]

I remember going through the whole django tutorial a decade ago 😄

Great points @tapadipti and @tibor-mach! I opened this PR to try to start making incremental improvements, but I've now also opened #5153 to suggest a higher-level restructure.

[tapadipti]

I'd added these 2 redirects, but they seem to be not working when I run this locally:

  "^/doc/start/model-management/model-registry$                                           /doc/start/model-registry/manage-models",
  "^/doc/start/model-management(/.*)?$                                                    /doc/start/model-registry$1",

Not sure what is wrong. @yathomasi any suggestions?

Other than this, LGTM.

[yathomasi]

It seems to be working with preview deployment so we should be fine to merge. BTW, the second rule would cover the first one as well.

https://dvc-org-start-add-model-crakny.herokuapp.com/doc/start/model-management/model-registry -> https://dvc-org-start-add-model-crakny.herokuapp.com/doc/start/model-registry/manage-models

https://dvc-org-start-add-model-crakny.herokuapp.com/doc/start/model-management/test -> https://dvc-org-start-add-model-crakny.herokuapp.com/doc/start/model-registry/test

I would suggest running build mode with yarn build and then run yarn start to test the redirects.

We did have it integrated for development mode with yarn develop, but it might be broken and we are okay with that as redirect logic is little separate from the gatsby project itself.

[tapadipti]

Thanks @yathomasi

BTW, the second rule would cover the first one as well.

Probably not, coz in the first one, the sub-page is also different: model-management/model-registry redirects to model-registry/manage-models