Dvc.org: docs: consolidate examples and higher level structure

[casperdcl]

Perhaps considering minimisation of the amount of pages which information is spread over.

For example, https://blog.codecentric.de/en/2020/01/remote-training-gitlab-ci-dvc/ links to https://blog.codecentric.de/en/2019/03/walkthrough-dvc/ for a DVC walkthrough rather than anything on dvc.org. It highlights how putting everything on one page means you can inject a lot more content and get a full overview a lot easier than breaking up into many pages.

We already have full tutorials on dvc.org (some essentially single page articles) but perhaps we should try to consolidate them.

My suggestion would be to have only e.g. 3 article pages (essentially beginner, intermediate, advanced) under a single "Get Started/Examples/Tutorials" heading.

As-is, it's super confusing to a newcomer what difference there is between:

• Get Started (1)
• Tutorials (1), (2)
• Use Cases (2)
• User Guide (1)
• Understanding DVC (2)

I'd recommend merging them into just 2 categories (marked (1) and (2)). Perhaps even including some content in "Command Reference" if needed. It's fine if there's duplication; it's not fine if readers are confused by the table of contents before they even know what page they need to be on, let alone what phrase to search for.

Note that these current headings are clear:

• Install
• Command Reference
• Changelog

---

• moved from #devrel discussion; CC @jorgeorpinel @Suor @andronovhopf @dmpetrov @shcheklein
• related https://github.com/iterative/dvc.org/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Adoc-content+get-started
• related #599

[shcheklein]

For example, https://blog.codecentric.de/en/2020/01/remote-training-gitlab-ci-dvc/ links to https://blog.codecentric.de/en/2019/03/walkthrough-dvc/ for a DVC walkthrough

It makes sense, right? :) They are optimizing theirs content. Not saying that we should not be optimizing docs structure (we are long overdue on this), but this particular argument probably is not that relevant.

I'd recommend merging them into just 2 categories (marked (1) and (2)).

I agree on merging Get Started and Tutorials. Get Started should become one of the Tutorials - Quick Start, Overview? Probably I would keep it split into sections though - it'll be more manageable.

I agree in merging Understanding DVC and User Guide. We even have a ticket for this. And a ticket to improve User Guide structure.

I would still like to keep Use Cases at the top level for now May be rename them to make it extra clear. We can decide on this later.

Changelog - we have a link to point to the Github releases.

Install - should probably go into User Guide (with a link to it on the new index page).

Command Reference, API Reference - stay the same.

[jorgeorpinel]

I agree on merging Get Started and Tutorials

➕1 but then would the first section in the docs nav be Tutorials, and its index the Get Started guide?

Probably I would keep it split into sections though - it'll be more manageable.

This is the main thing that Casper and Alex are suggesting we stop doing though. Have each full tutorial in a single page. Scroll/find > navigate/search

merging Understanding DVC and User Guide

Yes, will be done in #425

keep Use Cases at the top level for now May be rename them to make it extra clear

Our goal for use cases is that they serve as landing pages to our docs @casparjespersen so we want them in their own top level, but indeed they could be renamed to something more "marketable". Maybe Features (but we have already a Features page...) or just Uses?

Install - should probably go into User Guide

Not sure about this, let's discuss in #747?

[shcheklein]

This is the main thing that Casper and Alex are suggesting we stop doing though. Have each full tutorial in a single page. Scroll/find > navigate/search

Even though, it is still more of a tactical and quick to change/experiment with thing than Casper's suggestions to consolidate top level structures. That's why I'm not that worried about this one.

[shcheklein]

but then would the first section in the docs nav be Tutorials, and its index the Get Started guide?

there should its own index page with a good design that navigates User to the most common sections.

[casperdcl]

@jorgeorpinel you really need to stop bugging @casparjespersen. Also I think you meant to say @shcheklein rather than me anyway :D

[jorgeorpinel]

Oops

[jorgeorpinel]

@casperdcl note that we will be merging get-started into tutorials as part of #1051

[jorgeorpinel]

I think this is pretty much addressed, don't you think @casperdcl @shcheklein ? Should close?

[jorgeorpinel]

It's also kind of a duplicate of #144 — please move any pending items from here there. Closing!