docs: insufficient description of params

[skshetry]

https://github.com/iterative/dvc.org/blob/7546c1f45a435ebd7840426a9349c402e72bace1/content/docs/user-guide/dvc-files-and-directories.md#L153-L155

The link to parameter dependencies takes to the params where it's not clear where I find what it means (unless I read 341 words, who has time for it).

Also, the meaning of key paths is not clear, and makes it even more confusing since it talks about "referring to a ... file".

It also does not mention any way to specify a custom params file.

Discord Context: https://discord.com/channels/485586884165107732/563406153334128681/741913494991142932

[shcheklein]

Agreed, sentence is very confusing - it should be plain and explicit. I guess it comes from the fact that this doc initially was initially written as a reference for .dvc files, that were not human editable in its default mode. With 1.0 we have moved to some DVC language in "dvc.yaml", but haven't optimized docs for this.

I would suggest to do initial simple change though - one or two sentences to be more explicit. Ideally that should be enough.

[jorgeorpinel]

I agree that the text can be improved, but for context, we are talking about a bullet under "Each stage can contain the possible following fields:" in https://dvc.org/doc/user-guide/dvc-files-and-directories#dvcyaml-file. The goal here is to describe the fields inside dvc.yaml stages and what format they may have.

link to params where it's not clear where I find what it means

Idk. https://dvc.org/doc/command-reference/params starts it's Description with

In order to track parameters and hyperparameters associated to machine learning experiments in DVC projects, DVC provides a different type of dependencies: parameters.

[jorgeorpinel]

p.s. this is why we need a DVC Concepts guide (being worked on) and extract all these explanations from the cmd ref though (e.g. params, metrics, remote, etc.)

[shcheklein]

Glossary can definitely help here I think. Short explicit description in the tooltip should be enough. + a link to the long params command reference. Text should be fixed first though. One sentence change in this case can solve 80% of the problem.

[jorgeorpinel]

OK. See 6649f0a

[skshetry]

@jorgeorpinel, the dvc.yaml docs should be a guide rather than the reference. As it is, it's hard to translate that reference into a hand-written dvc.yaml file.

Just for params, it does not answer many of the questions which are essential to write a dvc.yaml stage (even in the new edition), such as:

1. What is a parameter dependency?
2. How do I track specific params?
3. How to track nested values of params?
4. How to use it for custom params file?

Something like Azure Pipelines' YAML Schema but concise and in a guide-format would be better to have.