get started: update index page #823
Conversation
static/docs/get-started/index.md
Outdated
| When you are done with _Get Started_ or if you'd like to try other alternatives | ||
| to learn DVC, check the available examples, interactive and community tutorials | ||
| on this [page](/doc/tutorials). |
There was a problem hiding this comment.
To cover more advanced topics step-by-step and with more in-depth explanations, please check out our various [Tutorials](/doc/tutorials).
There was a problem hiding this comment.
I would not say they are about advanced topics only
There was a problem hiding this comment.
OK just cover other topics or specific topics 🙂
There was a problem hiding this comment.
When you are done with _Get Started_ and want to cover other topics or if you'd like to try other ways to learn DVC?
There was a problem hiding this comment.
Hmm how about
To cover other topics step-by-step, more in-depth explanations, and even interactive scenarios, please check out our various [Tutorials](/doc/tutorials).
It's more compact. And why should we expect Get Started to be the first guide people follow before jumping to other stuff? Tutorials are also good to "get started" with DVC.
There was a problem hiding this comment.
I think I don't like two things.
Since tutorial is taken (by the section name) you had to use second order nouns like scenarios, explanations, etc. Instead actual ones - tutorial, example.
Also, step-by-step, more in-depth - not sure it gives much value to be honest.
There was a problem hiding this comment.
After you are done check this section for other examples, in-depth explanations, and interactive tutorials.
Hmmm sorry. We're really not on the same wavelengths on this particular sentence 🙁 I do like that this latest version is compact though! But:
- I'd start it
When you're done, feel free to check out... - I thought we didn't want to use the term "section"? Why is OK for /docs/tutorials? I still don't get why linking the word "tutorials" isn't the obvious choice.
- The Get Started is not really an example, how can you say "other examples"? This is why I like the term "scenario" better: because its more general, not to avoid using "tutorial".
- "step-by-step" tried to to the fact that you can actually reproduce the chapters/guide. But yes, maybe "end-to-end" or another similar term is better?
- "in-depth explanations" refers to the fact that tutorials may have more DVC internal/implementation details. Not sure this is always true though, but as long as some do, the usage of this phrase seems valid to me.
There was a problem hiding this comment.
But I feel this discussion is too consuming over a single paragraph. How about you decide based on everything above ^ (just try to use comma and "check out") and we merge this? We just ask everyone on Slack what they think about the sentence.
There was a problem hiding this comment.
Thanks! Made some final updates and merged.
I'd start it When you're done, feel free to check out.
👍 Thanks
I thought we didn't want to use the term "section"? Why is OK for /docs/tutorials?
👍 don't use it anymore. Though, see some points below ...
I still don't get why linking the word "tutorials" isn't the obvious choice.
Because in the sentence like this (that I had initially?):
check the available examples, interactive and community [tutorials](http://link.com)
linking like this means that examples do not have a link at all. The provided link is obviously related to interactive and community tutorials, not examples. So, it's just wrong. At least that's how I would read it.
The Get Started is not really an example, how can you say "other examples"
It can be considered as an example from a regular reader perspective. It's an examples on how one can use DVC to manage NLP pipeline and data artifacts involved. Again, it feels that we go too strict in a place where it's not that needed to my mind.
"step-by-step" tried to to the fact that you can actually reproduce the chapters/guide. But yes, maybe "end-to-end" or another similar term is better?
Because I don't fee it's important to specify that they are end-to-end. We have a full spectrum of them. And probably users would care more about feature coverage than about end-to-end-ness of the tutorials. So, it feels it can be omitted.
in-depth explanations
👍 I have added this. We had this before and indeed it makes sense to specify because at the very top we mention Get Started is not in-depth.
We just ask everyone on Slack what they think about the sentence.
let's not do this, too much attention to such a minor thing already :)
But I feel this discussion is too consuming over a single paragraph.
true! the only point I'm arguing and trying to clarify my position about, is that the documentation consists of different parts and it's fine to be very (mathematically) strict in some (command reference) and less so in others (get started, use cases, etc) for which I would prefer simplicity and readability over strictness.
There was a problem hiding this comment.
Because in the sentence like this...
I see. My suggestion was to not use the term "examples" there, so that's why for me linking "tutorials" seemed perfect.
It's an examples on how one can use DVC to manage NLP pipeline and data artifacts involved. Again, it feels that we go too strict...
Right, I guess an "example" (an instance serving to illustrate a rule or precept or to act as an exercise, see def.) can be very broad or very narrow depending on the context. The question is, an example of what?
I'm used to thinking about examples in our docs for more narrow things: specific command uses in cmd refs. But if we're talking broadly about ML project examples, then yes, Get Started and all tutorials are examples of that. Maybe I would just specify "data processing examples", or something like that.
I don't fee it's important to specify that they are end-to-end...
Noted.
it's fine to be very (mathematically) strict in some (command reference) and less so in others (get started, use cases, etc) for which I would prefer simplicity and readability
Understood. Again, my only note on this is in #823 (comment).
Fixes #739