params: clarify when they're granular

[jorgeorpinel]

Given that params defined at the top-level do not support granularity.

The only issue is that we currently tend to explain parameters as a "granular kind of dependency". So we should review these existing, older texts out there or find some other distinction like calling top-level params "general param files", or something else.

Originally posted by @jorgeorpinel in #4180 (comment)

See full #4180 (review) for other suggestions.

---

Related to #2412 ?

[jorgeorpinel]

Specific places where this issue exists now:

• https://dvc.org/doc/user-guide/glossary (find "Parameters"; also all tooltips use this) - text:

  They can be tracked as granular dependencies for stages of DVC pipelines (defined in dvc.yaml).

• https://dvc.org/doc/user-guide/pipelines/defining-pipelines#parameter-dependencies - text:

  A more granular type of dependency is the parameter...
  Params are granular dependencies because DVC only invalidates stages when the corresponding...

• https://dvc.org/doc/user-guide/project-structure/dvcyaml-files#parameters (by the bottom) - text:

  Params are a more granular type of stage dependency

Cc @skshetry @dberenbaum

[dberenbaum]

For dependencies, they are granular. Top-level params are not dependencies of any stage. We can further clarify, but I'm not sure I see anything inaccurate here.

[jorgeorpinel]

I'm not sure I see anything inaccurate

The problem I see is in the context because we now have these "top-level params" that are not really parameters in the way we've defined them before (granular dependencies) but they're called the same. Maybe each page is consistent internally but not vs. each other.

In fact this causes internal inconsistencies e.g. rn https://dvc.org/doc/user-guide/project-structure/dvcyaml-files#params has a tooltip (param dep text) in a possible context for top-level params:

[jorgeorpinel]

What's the purpose of top-level param definitions? Couldn't find much context from quickly skimming thgough iterative/dvc#8529 and #4180.

And I guess they all share a file-type definition (JSON/YAML/TOML key-pair files) so perhaps we can address via #2572 (comment) or even make a new reference section called File Formats (along with the CLI and APR refs).