search

iterative / katacoda-scenarios

Interactive Katacoda Scenarios
https://www.katacoda.com/dvc
2 stars 11 forks source link

review and cleanup structure #2

Closed shcheklein closed 3 years ago

shcheklein commented 4 years ago
dashohoxha commented 4 years ago

What is the difference between Basic Concepts, Get started?

"Basic Concepts" is an in-depth explanation of the basic concepts of DVC. The examples and situations (scenarios) used there are very basic (the most basic example possible to explain a certain feature). They are made up examples and have nothing related to ML. This is done in order to focus just in explaining and understanding the features.

Get Started on the other hand reflects the structure of the section "Get Started", which is meant as a quick scan of DVC features, with examples that looks like a real ML scenario, but without going into much details about each feature.

Need better explanation for global section. E.g. Basic Concepts, Basic concepts and features of DVC do not provide any explanation.

That concise explanation seems sufficient to me. But I am open to any suggestions.

Deduplicate Data With XFS And Reflinks - why is it top level section?

It is a left over from the early versions of the tutorials. It can be deleted because that topic is already covered in the other tutorials.

Examples -> Command Reference. I think in general it's better if we reflect docs structure with the katacoda sections

Maybe you are right. But right now most of the examples there are not from the Command Reference. Only the dvc fetch example is from the Command Reference. We can create another katacoda course named Command Reference and move dvc fetch there (with the intention of adding later other examples for the other commands).

shcheklein commented 4 years ago

"Basic Concepts" is an in-depth explanation of the basic concepts of DVC.

kk, probably it's better for Get Started to go first though. To reflect the docs structure.

Basic Concepts - I would love to see some connection between those and some part of the User Guide.

shcheklein commented 4 years ago

That concise explanation seems sufficient to me. But I am open to any suggestions.

Suggestion - the explanation that you gave me answering the previous question. So that I was able to understand some logic behind the structure.

Otherwise make them blank. Repeating the section name does not make any sense to me and do not provide any value.

shcheklein commented 4 years ago

dvc fetch

it's so peculiar choice that I'm actually tempted to suggest removing it completely. Then we can rename Example to Random Scenarios or something. And again put some description there so that we can understand the logic behind it.

dashohoxha commented 4 years ago

it's so peculiar choice

I did not choose it. My intention was to add other examples for other commands. But you suggested that working on User Guide was more important, so I couldn't do that.

shcheklein commented 4 years ago

so I couldn't do that.

Hide it for now then? It look strange to see fetch command reference alone :)

dashohoxha commented 4 years ago

Hide it for now then? It look strange to see fetch command reference alone :)

I would prefer to add a couple of other examples, so that it is not alone and it does not look strange, instead of hiding it. (Hiding it is the most easy thing anyway, and anyone can do it in a couple of minutes).

Actually my GSoD term is over, but this does not prevent me from contributing further, at least until some open issues are closed (if you also find this useful; I don't want to become boring or a burden).

shcheklein commented 4 years ago

I would prefer to add a couple of other examples

It would be nice. I would recommend focus on existing PRs first - we have too many things in play already.