guide: new Overview page #4006

jorgeorpinel · 2022-09-29T00:36:55Z

OP

Index page: remove?

What is DVC: dissolve into some page outside the user guide (and maybe in the home page/outside of docs).

Note that clicking the UG nav entry will now open directly in https://dvc.org/doc/user-guide/project-structure (for now).

UPDATE:

Per #144 (comment):

turn it into an Overview instead, which would combine its existing Core Features section as well as Related Technologies (which also addresses "Related Technologies: dissolve into some page" from the OP).

Also moves/reinforces other sections of What is DVC? in other existing docs.
Updates links and redirects accordingly .

In review app: https://dvc-org-guide-break-up--bvcwlb.herokuapp.com/doc/user-guide

(the latter from sidebar only for now)

github-actions · 2022-09-29T00:49:18Z

0aa5585

Link Check Report

There were no links to check!

jorgeorpinel · 2022-09-29T02:33:23Z

content/docs/user-guide/what-is-dvc.md

-Data science experiment sharing and collaboration can be done through a regular
-Git flow (commits, branching, pull requests, etc.), the same way it works for
-software engineers. Using Git and DVC, data science and machine learning teams


Most of this is already mentioned in the docs home and Exp Mgmt docs so I'm just removing it.

However, some changes to the ML experiment management text in the home page could recover some of these ideas (rel DVC home page + updates #3833).

and remove Core Features header (tmp)y

jorgeorpinel · 2022-09-29T03:44:27Z

UPDATE: Actually, per #144 (comment) I'm going to transform the Core Features section of What is DVC? as well as the Related Technologies page into an overview for the UG. For now it will be the first sub-page (no index page) but it could also be the index page itself. WDYT @dberenbaum ?

+ link fix

into new Overvie page per #4006 (comment)

jorgeorpinel · 2022-09-29T17:03:06Z

content/docs/sidebar.json

-    "source": "user-guide/index.md",
+    "source": false,
    "children": [
-      {
-        "label": "What is DVC?",
-        "slug": "what-is-dvc"
-      },
+      "overview",


Or should we use the UG index page for Overview? No strong opinion

jorgeorpinel · 2022-09-29T17:05:36Z

redirects-list.json

+  "^/doc/user-guide/what-is-dvc$                                                          /doc/user-guide/overview 302",
+  "^/doc/user-guide/related-technologies$                                                 /doc/user-guide/overview 302",


302s for now in case we later decide to move it to the UG index page instead, though

jorgeorpinel · 2022-09-29T17:06:57Z

content/docs/user-guide/overview.md

+## Comparison with Related Technologies

 DVC combines a number of existing ideas into a single tool, with the goal of
-bringing best practices from software engineering into the data science field
-(refer to [What is DVC?](/doc/user-guide/what-is-dvc) for more details).
+bringing best practices from software engineering into the data science field.
+
+<details>

-## Git
+### Git


This section is moved verbatim for now. I just put each technology into collapsed sections so the Overview page stays short (on the surface at least).

shcheklein

It goes in the right direction, I think .. we can do structural changes like this quick and iterate on the content later

jorgeorpinel · 2022-09-29T18:22:37Z

Sounds good! There's a separate task to combine Core Features and Feature pages (both rel #144 (comment) and #3833) so I suppose we can merge this indeed 🙂

jorgeorpinel · 2022-09-29T18:24:12Z

content/docs/user-guide/what-is-dvc.md

-## DVC does not replace Git!
-
-DVC files such as `dvc.yaml` and `.dvc` files serve as placeholders to track
-large data files and directories for versioning (among other
-[purposes](/doc/user-guide/project-structure)). These metafiles change along
-with your data, and you can use Git to place them under
-[version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control)
-as a proxy to the actual data versions, which are stored in the <abbr>DVC
-cache</abbr> (outside of Git). This does not replace features of Git.
-
-DVC does, however, provide several commands similar to Git such as `dvc init`,
-`dvc add`, `dvc checkout`, or `dvc push`, which interact with the underlying Git
-repo (if one is being used, which is not required).


This has been fully removed although the point has also been stressed in other existing docs but I'm not sure it's mentioned everywhere it should -- so that's another possible minor follow-up to this.

jorgeorpinel · 2022-09-29T18:25:28Z

Cc @dberenbaum just FYI on this change (review no longer needed but if there's any feedback feel free to leave it).

jorgeorpinel · 2022-10-04T06:22:23Z

UG Overview page deployed ⚓

Note that Studio docs have a similar page called How it works, so this may be a bit of a pattern to keep in mind.

guide: remove index page and What is DVC?

bd14b24

(the latter from sidebar only for now)

jorgeorpinel added A: docs Area: user documentation (gatsby-theme-iterative) C: guide Content of /doc/user-guide labels Sep 29, 2022

jorgeorpinel self-assigned this Sep 29, 2022

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 00:37 Inactive

doc: move WID? intro to Home

2c224fa

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 00:46 Inactive

jorgeorpinel added the p1-important Active priorities to deal within next sprints label Sep 29, 2022

doc: bring more intro info from WID?

61116c8

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 02:32 Inactive

jorgeorpinel commented Sep 29, 2022

View reviewed changes

jorgeorpinel changed the title ~~guide: remove index page and What is DVC?~~ guide: remove index page and What is DVC Sep 29, 2022

guide: remove links to WID

26af155

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 02:35 Inactive

guide: make WID diagram a bullet and (tmp)

22f66fa

and remove Core Features header (tmp)y

jorgeorpinel force-pushed the guide/break-up-intro branch from f619ffe to 22f66fa Compare September 29, 2022 02:39

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 02:39 Inactive

jorgeorpinel requested a review from dberenbaum September 29, 2022 03:14

This comment was marked as outdated.

Sign in to view

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 03:21 Inactive

jorgeorpinel mentioned this pull request Sep 29, 2022

docs: "definitive" organization #144

Closed

jorgeorpinel removed the request for review from dberenbaum September 29, 2022 03:43

doc: Git does not replace (or include) Git +

7106b67

+ link fix

jorgeorpinel force-pushed the guide/break-up-intro branch from 4b1eff0 to 7106b67 Compare September 29, 2022 03:46

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 03:46 Inactive

jorgeorpinel changed the title ~~guide: remove index page and What is DVC~~ guide: replace What is DVC and Related Technologies with Overview (and other sections) Sep 29, 2022

jorgeorpinel added 2 commits September 29, 2022 12:48

Merge branch 'main' into guide/break-up-intro

080fc90

guide: combine Core Feats and Related Tech into

4fe5540

into new Overvie page per #4006 (comment)

jorgeorpinel marked this pull request as ready for review September 29, 2022 16:58

shcheklein deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 16:59 View deployment

jorgeorpinel changed the title ~~guide: replace What is DVC and Related Technologies with Overview (and other sections)~~ guide: new Overview page Sep 29, 2022

jorgeorpinel commented Sep 29, 2022

View reviewed changes

shcheklein approved these changes Sep 29, 2022

View reviewed changes

guide: remove comments, lower diagram bullet

6a2b912

shcheklein temporarily deployed to dvc-org-guide-break-up--bvcwlb September 29, 2022 18:22 Inactive

jorgeorpinel commented Sep 29, 2022

View reviewed changes

jorgeorpinel merged commit 0aa5585 into main Sep 29, 2022

jorgeorpinel deleted the guide/break-up-intro branch September 29, 2022 18:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide: new Overview page #4006

guide: new Overview page #4006

jorgeorpinel commented Sep 29, 2022 •

edited

Loading

github-actions bot commented Sep 29, 2022 •

edited

Loading

jorgeorpinel Sep 29, 2022 •

edited

Loading

This comment was marked as outdated.

jorgeorpinel commented Sep 29, 2022

jorgeorpinel Sep 29, 2022

jorgeorpinel Sep 29, 2022 •

edited

Loading

jorgeorpinel Sep 29, 2022

shcheklein left a comment

jorgeorpinel commented Sep 29, 2022

jorgeorpinel Sep 29, 2022

jorgeorpinel commented Sep 29, 2022

jorgeorpinel commented Oct 4, 2022 •

edited

Loading

		"^/doc/user-guide/what-is-dvc$ /doc/user-guide/overview 302",
		"^/doc/user-guide/related-technologies$ /doc/user-guide/overview 302",

guide: new Overview page #4006

guide: new Overview page #4006

Conversation

jorgeorpinel commented Sep 29, 2022 • edited Loading

github-actions bot commented Sep 29, 2022 • edited Loading

Link Check Report

jorgeorpinel Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

This comment was marked as outdated.

jorgeorpinel commented Sep 29, 2022

jorgeorpinel Sep 29, 2022

Choose a reason for hiding this comment

jorgeorpinel Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

jorgeorpinel Sep 29, 2022

Choose a reason for hiding this comment

shcheklein left a comment

Choose a reason for hiding this comment

jorgeorpinel commented Sep 29, 2022

jorgeorpinel Sep 29, 2022

Choose a reason for hiding this comment

jorgeorpinel commented Sep 29, 2022

jorgeorpinel commented Oct 4, 2022 • edited Loading

jorgeorpinel commented Sep 29, 2022 •

edited

Loading

github-actions bot commented Sep 29, 2022 •

edited

Loading

jorgeorpinel Sep 29, 2022 •

edited

Loading

jorgeorpinel Sep 29, 2022 •

edited

Loading

jorgeorpinel commented Oct 4, 2022 •

edited

Loading