build a "Tutorials" top-level index page

[dashohoxha]

This page should have a list of tutorials, with a short description of each tutorial.

The first tutorial is going to be the "Get Started Tutorial", which is the most detailed one and full of comments, explanations, and links to other resources.

The other tutorials are links to interactive Katacoda tutorials.

Maybe we can also list some tutorials that are explained on external blog pages.

[dashohoxha]

By the way, I am planning to merge this: https://dvc.org/doc/get-started/example-pipeline
and this: https://dvc.org/doc/tutorial and to make an interactive tutorial based on them (which is going to be something like this: https://katacoda.com/dvc/courses/tutorials/versioning).

This implies that the the two pages mentioned above, as well as this one: https://dvc.org/doc/get-started/example-versioning are going to be removed from the structure of the docs, since they will be replaced by interactive tutorials.

[shcheklein]

By the way, I am planning to merge this: https://dvc.org/doc/get-started/example-pipeline
and this: https://dvc.org/doc/tutorial

I think there is a ticket to consolidate NLP example and tutorial (by simplifying tutorial). Again, I don't see how this can be replaced by Katacoda. I would expect it to have a link to Katacoda for those who want to run. Similar to Pytorch's Run in Colab, etc.

are going to be removed from the structure of the docs, since they will be replaced by interactive tutorials.

I consider online tutorials complementary but not as a replacement for text based docs. There are a lot of reasons for this, major are:

• we can't depend on a third party service for the core flows - no guarantees they will stay and work, no SEO, we don't control quality (highlighters, links to commands, diagrams), most likely limited in terms what can be done
• interactive vs text - is a matter of taste and there no reason to not have both

[shcheklein]

@jorgeorpinel could you please, link the related consolidation tickets here please? and other related issues that come to your mind.

[jorgeorpinel]

Sure:

• I think user-guide/get-started: reorganize "Understanding DVC" section #425 unbundle "Understanding DVC" docs is the oldest one.
• No, actually this one is older: guide: extract part of theconfig cmd ref. #340 config: split up cmd ref into user guide + cmd ref (but currently assigned to a contributor)
• This would be a new section: api: create documentation #463 document DVC API
• Another new section: guide: new DVC Concepts section #550 new "Basic Concepts" doc(s)
• ➡️ This one specifically relates to tutorials: reorganize get-started examples into tutorials #564 reorganize get-started examples into tutorials
• Finally, cases: generalized shared dev server #654 use-cases: extract them into actual articles?

I hope I didn't miss any other one.

[dashohoxha]

I consider online tutorials complementary but not as a replacement for text based docs.

We can have them both. I don't see any problems with this.

we can't depend on a third party service for the core flows - no guarantees they will stay and work

This is a valid concern. I have been thinking about it myself as well.

However notice that the code of the interactive lessons is just markdown (with small extensions), for example: https://github.com/iterative/katacoda-scenarios/blob/master/basics/pipelines/step1.md
It is possible to convert them automatically to pure markdown (or to extend our engine to display them properly). Then to try these commands, all you need is an ubuntu-18.04 docker container.

So, in case that Katacoda somehow perishes, not everything is lost. We can publish ourselves the content of the lessons, and the users will have to use a docker container to try them, which is not a big inconvenience.

[dashohoxha]

I think there is a ticket to consolidate NLP example and tutorial (by simplifying tutorial).

I have just finished an attempt of consolidating these two tutorials (https://dvc.org/doc/get-started/example-pipeline and https://dvc.org/doc/tutorial).
The resulting online tutorial is here: https://katacoda.com/dvc/courses/tutorials/pipelines
This part has not been included yet: https://dvc.org/doc/tutorial/sharing-data

I am going to list this one as well on the Tutorials index page.

[shcheklein]

@dashohoxha

We still need to decide what should we do with the lengthy one. It includes a lot of information. May be put some of those explanations as expandable sections into the former example-pipelines? I also, don't know what should we do with sharing-data and other info about DVC that overlaps with basics, get-started, etc. @jorgeorpinel what are your thoughts about this?

Some feedback on the new tutorial:

1. It looks like this new interactive tutorial is purely based on the example-pipeline? If it's the case, I would just modify example-pipeline to have a link to the interactive version. Not sure if it makes sense to include it as an item in the Tutorials section - we'll have three versions of the same thing that way.
2. It feels that it lacks some explanations (like you do cat or a tree and I don't know what should I be paying attention to). It might fine if it comes as a complimentary to the text/wordy version.
3. Do you know if Katacoda has hot keys to execute commands with? It's annoying that I have to click every code line to get the final result.
4. It's annoying that I can't just press a button to play the whole step, or all the previous steps. Or may be I'm missing it somewhere in the interface?

[shcheklein]

Btw, https://kubernetes.io/docs/tutorials/ - is a good example on how can we organize and integrate interactive tutorials and text versions.

[dashohoxha]

We still need to decide what should we do with the lengthy one. It includes a lot of information. May be put some of those explanations as expandable sections into the former example-pipelines?

It seem to me that the explanations on the Long Tutorial are replicated all over the rest of the docs. So, if we just drop it, I think we are not going to loose much (especially considering that it is a bit outdated and seems to be broken).
Besides this, on the Community Tutorials section, the first blog is this one: https://blog.dataversioncontrol.com/data-version-control-tutorial-9146715eda46 which is exactly the same as the Long Tutorial.

I also, don't know what should we do with sharing-data

I didn't include it in the interactive tutorial (https://katacoda.com/dvc/courses/tutorials/pipelines) because I don't see how to make this part interactive. However I am sure that there are similar examples about sharing data elsewhere in the docs.

1. It looks like this new interactive tutorial is purely based on the example-pipeline? If it's the case, I would just modify example-pipeline to have a link to the interactive version. Not sure if it makes sense to include it as an item in the Tutorials section - we'll have three versions of the same thing that way.

I think that it is better to keep them as separate items (as they are now). Also they are not exactly the same. The interactive tutorial covers more scenarios than the native one.

2. It feels that it lacks some explanations (like you do cat or a tree and I don't know what should I be paying attention to). It might fine if it comes as a complimentary to the text/wordy version.

It is so because some things have been explained previously. In particular, it is assumed that at least the Basics and Get-Started have been finished before starting a ML tutorial. Those cat and tree are just to track what is happening. The user could normally do them himself, but I am putting them there just as a reminder and as a convenience.

3. Do you know if Katacoda has hot keys to execute commands with? It's annoying that I have to click every code line to get the final result.

I don't know. But the student is assumed to type the commands on the terminal, because this way he can benefit most from the tutorial. Clicking the command (which makes an automatic copy/paste) is just a convenience. It is useful for example for me, when I go through the tutorial to check it.

4. It's annoying that I can't just press a button to play the whole step, or all the previous steps. Or may be I'm missing it somewhere in the interface?

Katacoda does not have such a feature, but it allows you to upload scripts in the virtual machine. Then you can instruct users to run those scripts, or you can tell Katacoda to run them automatically at the beginning of the step.

[dashohoxha]

Btw, https://kubernetes.io/docs/tutorials/ - is a good example on how can we organize and integrate interactive tutorials and text versions.

The kubernetes page seems to be an exemplary page for all the docs, not just for the interactive tutorials :) We can try our best, but I am not sure whether we can match their quality.

But honestly, I think that each software has its own specifics, so something that works well for one of them may not work so well for another. We see this for example when we try to compare DVC and Git.

I also don't like that they embed Katacoda scenarios on their doc pages. This makes it less comfortable to work with them.