Outline of docs structure

[dberenbaum]

Opening for discussion. We recently finished moving all the remote info from the command reference to distinct user guides. I think it's way more organized now, but I worry that it's too deeply nested inside user-guide->data-management->remote storage.

We know that this is some of the most frequently visited info, and so is user-guide->project structure->dvc.yaml files. Can we create a top-level reference section that includes remotes, project structure, CLI, and Python references? I think it would help make these pages easier to find and create a cleaner separation between more narrative guides and technical reference material.

Proposed structure would look like:

• User guide
  • Data management
  • Pipelines
  • Experiment management
    ...
• Reference
  • Project structure
  • Remote config
  • Commands
  • Python API

[shcheklein]

Sounds good to me, @dberenbaum !

[shcheklein]

Project structure should become more like a Project file or something? I don't like this name, but can't come up with something better ... dvc.yaml reference?

Remote config - I wonder if we should do one Config reference - include remotes there (w/o additional level, all things about remotes and config on the same level).

[dberenbaum]

Project structure should become more like a Project file or something? I don't like this name, but can't come up with something better ... dvc.yaml reference?

Agreed, I think we need to make it better than project structure, which sounds more like we are giving suggestions on how to organize your project. Right now, it includes more than dvc.yaml but also any other DVC-managed files.

Remote config - I wonder if we should do one Config reference - include remotes there (w/o additional level, all things about remotes and config on the same level).

Makes sense. Would we want subpages for each remote like we now have in the guide? Then it becomes as nested as it is now, so now I'm second guessing this 😅 .

[shcheklein]

I think we can keep it:

Reference
   Config
       SSH
       Google Drive
       ...
       Cache 
       [Other config ....]

wdyt?

[dberenbaum]

It could work, or it might be too busy.

Let's put this as a p2 for now. We have already moved this info around a lot. I'd rather focus on get started and new content focused on basic workflows than on moving around the existing content.

[dberenbaum]

Another benefit would be to have somewhere to mention environment variables

[dberenbaum]

Bumping the importance here but also want to consider other changes to consolidate the dvc/mlops docs (dvc, dvclive, studio, vs code)