Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

build a "Tutorials" top-level index page #657

Closed
dashohoxha opened this issue Sep 30, 2019 · 10 comments · Fixed by #666
Closed

build a "Tutorials" top-level index page #657

dashohoxha opened this issue Sep 30, 2019 · 10 comments · Fixed by #666
Labels
A: docs Area: user documentation (gatsby-theme-iterative) type: enhancement Something is not clear, small updates, improvement suggestions

Comments

@dashohoxha
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Member

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 shcheklein added A: docs Area: user documentation (gatsby-theme-iterative) type: enhancement Something is not clear, small updates, improvement suggestions tutorial labels Sep 30, 2019
@shcheklein
Copy link
Member

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

@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Oct 1, 2019

Sure:

I hope I didn't miss any other one.

@dashohoxha
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link
Member

@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
Copy link
Member

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

@dashohoxha
Copy link
Contributor Author

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.

  1. 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.

  1. 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.

  1. 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
Copy link
Contributor Author

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.

shcheklein added a commit that referenced this issue Oct 4, 2019
Fix #657: Reorganize tutorials into their own section.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A: docs Area: user documentation (gatsby-theme-iterative) type: enhancement Something is not clear, small updates, improvement suggestions
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants