guide: updates to dvc.yaml spec

[jorgeorpinel]

Extracted from #3414 (comment)

This page should focus on the schema/spec of the file and it's sections more than guidance and explaining concepts, since we'll have a guide for that now (see #3414).

[dberenbaum]

@jorgeorpinel What's the status of this PR? Is it still needed?

[jorgeorpinel]

I'm not sure how this PR got so complicated 😓 but yes, after mergingmain (resolved a bunch of conflicts) I see many useful changes here. I will have to split this though, otherwise it's too hard to review... ⏳

[jorgeorpinel]

All this I just moved up unchanged. It started in old line 506 before.

[dberenbaum]

Thanks @jorgeorpinel! LGTM except confused why it says 88 commits?

It would help me better manage the docs workload if we can be a little more careful about what changes are worthwhile. If the PR was all about making it more of a spec and less of a guide it would make more sense, but most changes look like minor, subjective style issues. If we can reduce some of those, I hope it can help reduce noise and focus more on what's important. I know you don't intend for me to have to review everything right away, but it would help to cut out the unimportant stuff altogether instead of having to try to figure it out as I review the PR. 🙏

What do you think?

[jorgeorpinel]

It's 88 commits because this was started in July. I later removed a bunch of changes.

Agree about the relevance of these changes. At that time I already had a bunch of edits stashed for this file which I didn't manage to propose since they never seemed major enough so eventually I just made the PR (and then it grew out of control).

But don't worry, in the new docs process, this kind of work is not something I'll be paying much attention to in the foreseeable future.

[github-actions]

548749a

Link Check Report

There were no links to check!