Dvc.org: cmd ref: add `commit` example on adding missing dependency to existing pipeline

[jorgeorpinel]

Copy from https://discordapp.com/channels/485586884165107732/563406153334128681/620641589252980736

[jorgeorpinel]

@shcheklein you mentioned:

we would need to decide how to mix existing examples based on get started and simple command line ones

Not sure what you meant.

[shcheklein]

cc @dashohoxha (should be of you interest to read this, I think)

Not sure what you meant.

So, if we take a look at the dvc commit examples we have now in the command reference they all use example-get-started repo as a base. You don't need to do mkdir or create some artificial bash processing, you just do git clone examples-get-started and then use pull, repro, commit, etc.

The benefits are:

• Unified across different commands
• Can actually run them if you want
• Use actual data and more or less actual scenarios - which should resonate better with actual practitioners
• Examples can be simpler - don't need to repeat dvc init, makedir, etc every time. You can focus on actual stuff.

The cons are:

• Include a hidden setup your environment section everywhere, which is unified, but more complicated than mkdir repo && cd repo && dvc init.
• Sometimes it's actually easier to see the essence of the command in a simple bash script (not sure about this).
• anything else I'm missing?

On the other had we have examples like in dvc move or similar. They use some artificial names, they are sometimes not even runnable - they just illustrate the concept. Sometimes they are actionable, but then you have to provide some artificial scripts to generate the project, data, scripts - which can be easy, can be not.

I see benefits in both types, but we will need to come with some logic on how to mix them. May be use a separate title:

## Examples: TL;DR.

:)

## Examples: Actual actionable examples

[dashohoxha]

@shcheklein @jorgeorpinel I agree that both kinds of examples are useful, depending on the case.

When we use real life examples (like example-get-started), it is often the case that several concepts and features are intertwined. Sometimes this makes it a bit difficult to explain just a single concept/feature without having to explain the others as well (or referring to other explanation pages).

This is where a simple bash script may be useful. It can be minimal and focus just on the concept or feature that needs to be explained, although it may look like an unrealistic situation. This minimalism makes it easier for the reader to grasp the concept that we are trying to explain.

This is what I am doing with Katacoda scenarios. I am trying to compose minimal scenarios where I can explain the basic features of DVC in small steps. When the collection of these scenarios is completed, I believe that it would be possible to refer some of them from the command-reference pages (or user-guide pages) in order to illustrate some of the concepts/features related to a command.

Besides this, I think that it should be useful to have a collection of simple bash script examples (similar to katacoda scenarios) which illustrate a certain concept/feature. Dev guys are using them frequently to clarify a certain situation (because it is difficult to explain something with words and it is easy to explain it with examples), so why not use them to explain things to the new users? We can have a separate repository where we collect such scripts, and we can refer to them from the doc pages. (Maybe I should start another issue for discussing this.)

In general, I think that it is better to not clutter the command-reference pages with lengthy examples, but to keep the examples as bash scripts in a separate repository and to have links to these examples from the man pages.

[imhardikj]

@jorgeorpinel This issue is currently mentioned for update in #1824 but it almost similar to #1840, except in this case it's dependency and not output. Should this be a separate How-to doc?

[jorgeorpinel]

Good catch @imhardikj! It's basically the same how-to so let's merge this to #460 please, and close here. Please then unlink #1840 from #460 since it won't fix it completely, and make another PR once #1840 is merged to finish the dependency part. Thanks