Get started consolidation

[dberenbaum]

There are some common themes I notice in feedback on our docs:

• Unclear where to start
• Too many options
• Info feels scattered
• Too much effort/takes too long to onboard

We have simplified the experience for features like experiment tracking and model registry, but users now have to choose a path before knowing anything about DVC, and these entrypoints feel lacking without understanding the fundamentals of data versioning.

I think we should streamline back to a single entrypoint where we introduce data versioning. When we had a single path, I recall users were more complimentary of our docs.

We can keep most of our existing get started docs as secondary entrypoints. Users who want to start there should still be able to do so independently.

Action items:

• Make data versioning the primary entrypoint
  • Merge https://dvc.org/doc/start/data-management/data-versioning into https://dvc.org/doc/start
  • Migrate all of Get Started to example-get-started-experiments - not critical but this is better maintained and will help unify things (experiment tracking or model registry won't require context switch)
  • Add colab notebook or other paths to optimize/make it easier
  • Introduce Studio
• Optimize secondary entrypoints
  • Model registry docs consolidation #5133
  • Experiment tracking consolidation
  • Data pipelines consolidation

Related:

• Model registry docs consolidation #5133
• Quickstart #4919
• Outline of docs structure #4381

[tapadipti]

Add action point:

• Studio docs should be used only for Studio-specific things like team management, billing, on-premises hosting, etc. The rest of the Studio docs should be consolidated with the dvc docs.

@dberenbaum You probably meant this in your Optimize secondary entrypoints action items, but I think it'll be better to mention this specifically, so that we don't miss it later.

[dberenbaum]

@tapadipti I was trying to limit the scope of this issue, so I only included get started items. After I started #5133, I realized we might need a higher-level plan and to prioritize which changes will be most impactful.

I wanted to discuss issues like how to consolidate Studio docs in either #4381 or in a new issue. Can we keep that discussion separate?

[tibor-mach]

I agree with the consolidation but I would include more than data management. The way I see this is that this first entry point should be a very quick tour of the main DVC features and concepts - so I'd pick data versioning, experiments, model registry...and mention other stuff in passing, linking to specific guides as you suggest (e.g. for DVC pipelines).

If all people see is data management but they are mostly concerned e.g. with properly versioning artifacts, they might lose interest. They might also assume that what we show them in the quickstart guide is most of what DVC offers (which I think is a reasonable assumption).

Also, I would not expect people to really be onboarded in the sense that the quickstart should not be enough to actually start working on your own stuff. But they should be on board in the sense that they that DVC can actually help them (and so is worth their time) and they know which guide(s) to read to address those issues.

[dberenbaum]

Thanks @tibor-mach. Also adding a link to your slack discussion and proposal for context.

We have an intro to what dvc does on the front page of dvc.org today:

Screen.Recording.2024-02-27.at.7.50.22.AM.mov

...and in the readme.

We definitely need users to understand what DVC is for before showing them how to use it. Do we need to revise these, or add something similar (like your notebook) elsewhere, like in https://dvc.org/doc? Is the interactivity of a notebook important if we are not yet showing how to use it? What do you think about revising the existing notebook rather than creating another repo and notebook (consolidation rather than proliferation)?

I expected that by the time the users reach getting started, they are looking for how to use DVC. I have been more focused on reducing choices and guiding users on where and how to start. IMHO users struggle doing anything in our ecosystem until they understand how DVC versions data. We always end up referring back to how to track data with DVC, how to set up remote storage, etc.