guide: reorg sidebar

[dberenbaum]

Proposed restructure of the guide based on discussion at the bottom of #144. I only updated the sidebar so we can iterate on that before propagating the changes elsewhere.

[github-actions]

d328427

Link Check Report

There were no links to check!

[shcheklein]

The only thing that raises some concern from my end. It should not be in the data management to my mind. I think pipelines deserve their own place in the UG. It's just content should be very different as we were discussing in the PR for the pipelines.

[dberenbaum]

I struggled to keep them separate because:

1. I wasn't sure where to put external-dependencies (and managing-external-data/external outputs to a lesser extent) since they are about external data but only really make sense in the context of pipelines.
2. Pipelines in general is tightly coupled with data management now (I would like to address this on the product side, but it's not going to happen this year).
3. From a use case perspective, I can see an argument for keeping them together (a typical data engineering workflow needs data versioning and pipelines).

Still, I'm happy to keep pipelines separate and agree it seems like a more natural structure (see my comments at the bottom of #144). Where would you suggest to put external-dependencies and managing-external-data?

[shcheklein]

since they are about external data but only really make sense in the context of pipelines.

Hmm, it think the both could be used independently though? Especially external outputs (like versioning an external directory).

Even if that is the case, then we should move them into pipelines, out of the data management.

[dberenbaum]

What about something like this (not sure how to format it correctly):

      {
        "label": "Data Management",
        "slug": "data-management",
        "children": [
            "large-dataset-optimization",
            {
              "label": "Managing External Data",
              "slug": "managing-external-data"
            }
        ]
      },
      {
        "label": "Pipelines",
        "slug": "pipelines",
        "children": [
            "defining-pipelines",
            "external-dependencies",
            {
              "label": "External Outputs",
              "slug": "external-outputs",
              "source": "/docs/user-guide/managing-external-data"
            }
        ]
      },

[shcheklein]

Yep, sounds reasonable to start with. We'll need to move imports I think into data management as a next step then.

[dberenbaum]

Ah, I didn't catch your point about imports before. In that case, we can duplicate both sections:

      {
        "label": "Data Management",
        "slug": "data-management",
        "children": [
            "large-dataset-optimization",
            {
              "label": "Importing External Data",
              "source": "/docs/user-guide/pipelines/external-dependencies"
            },
            {
              "label": "Managing External Data",
              "slug": "managing-external-data"
            }
        ]
      },
      {
        "label": "Pipelines",
        "slug": "pipelines",
        "children": [
            "defining-pipelines",
            "external-dependencies",
            {
              "label": "External Outputs",
              "source": "/docs/user-guide/data-management/managing-external-data"
            }
        ]
      },

[shcheklein]

yep, don't know if that is possible though :) (would be a nice feature it is possible)

[jorgeorpinel]

I don't think it's ideal to have page duplicates like that. I'd consider it a patch for either a product or docs content issue that should be resolved.

[shcheklein]

Good stuff, I would reconsider the pipelines part. Otherwise LGTM (maybe we need some redirects)

[jorgeorpinel]

Minor (could be a follow-up) in terms of order and page naming:

Suggested change

	"running-dvc-on-windows",
	"setup-google-drive-remote",
	"stop-tracking-data",
	"update-tracked-data",
	"add-deps-or-outs-to-a-stage",
	"resolve-merge-conflicts",
	"share-a-dvc-cache"
	"run-dvc-on-windows",
	"stop-tracking-data",
	"update-tracked-data",
	"resolve-merge-conflicts",
	"add-deps-or-outs-to-a-stage",
	"setup-google-drive-remote",
	"share-a-dvc-cache"

[dberenbaum]

TBH I think they're fine as is. For example, I intentionally put windows and google drive at the top since they are blockers for doing almost anything for those users.

[jorgeorpinel]

OK but (minor)

• should it be (how to) run-dvc-on-windows (not running)
• the one for GDrive may be moved in the future again right? Into data management/ remote setup (see guide: extract remote add/modify details from cmd ref. #2866)

[jorgeorpinel]

Possibly follow-up

Should the Parallel Coordinates Plot section be moved or linked from the Visualizing Plots page?

[dberenbaum]

I don't think it should be moved since it's more related to comparing experiments, but linking could make sense.

[jorgeorpinel]

A bunch of link updates should follow this. Fun fun... Lmk if you need help!

p.s. I think this would basically close #144 ? (finally)

[jorgeorpinel]

An alternative to consider (from #144 (comment)) which may be better since we don't love the product feature as-is now (I think):

External Deps/Managing External Data: ... or make them only reachable via links.

[jorgeorpinel]

p.s. should also update the H1 in importing-external-data.md

[dberenbaum]

or make them only reachable via links.

I like it better than having no solution for using data directly from the cloud, so I'm going to keep it in.

[dberenbaum]

A bunch of link updates should follow this. Fun fun... Lmk if you need help!

I guess it's not that bad, but it seems like the redirects should make it a pretty low priority, right?

An auto update script when adding redirects would be 🔥 .

[jorgeorpinel]

the redirects should make it a pretty low priority

Not sure. Will we remember what links to update if we don't do it soon?

auto update script

Prob overkill: we mainly need to run find/replace per link throughout content/docs 🙂

[dberenbaum]

Good feedback @jorgeorpinel and @shcheklein! If one of you want to do one more pass, I'll merge if everything looks good.

[jorgeorpinel]

LGTM. I started another PR for the links: #4015