cases: Versioning Data and Model Files (review)

[jorgeorpinel]

Addresses #820

• + Simplify the Use Cases index (dvc.org/doc/use-cases)
• Language review + copy edits
• Refocus writing (remove distracting parts).
• Give it a better structure.
• Reference other docs more.

---

• Be very clear and explicit about the role of DVC vs Git
• Expand on run/dag (pipelines) and/or dvc.yaml/lock versioning.

---

• Rewrite as a higher level Explanation. See cases: Versioning Data and Model Files (review) #1716 (comment)
• Fix and improve links from other docs to this case and its's tutorial.
• Extract How-to steps into actual how-to guide? (hidden for now, see guide: begin How To section #1705) Extracted to cases: extract how-to/tutorial parts into separate pages #1722

[shcheklein]

To be honest I don't see any major changes. What I would expect is that we go at least one level up in terms of how we explain this use case. It is still very technical, with exact commands, etc. We should migrate this into tutorials, how-tos

[jorgeorpinel]

BTW, based on https://documentation.divio.com/introduction/ Use Cases are not fully documentation... They are part Explanation I guess, and they can contain some How-to steps (in fact the Shared Cache one is one of our most popular "tutorials", I think). But they're also 50% marketing, closer to our current https://dvc.org/features page sections.

May be interesting to pull them out of /docs, even merge with /features perhaps. Moving the How-to parts to the actual /how-to docs of course (and link from the use case). This would make them proper landing pages (possibly with their own design, even).

[jorgeorpinel]

I would expect is that we go at least one level up in terms of how we explain this use case. It is still very technical

I simplified the intro and DVC is not Git! sections of the use case. See https://dvc-landing-use-cases-iezica0y.herokuapp.com/doc/use-cases/versioning-data-and-model-files.

The rest of the content was also updated but it will need to be migrated like you mentioned, and just briefly mentioned//linked to the new location. However that's also the case for all other use cases including Data Registries, and depends a little on having started the How-to section (in progress, see #899). So can we try to merge this and let me do the same initial simplification to the remaining use cases @shcheklein ?

I'll open a separate issue for migrating the how-to/tutorial parts. See #1722

I also improved mentions of the versioning case and it's tutorials throughout the docs.

[jorgeorpinel]

So can we try to merge this and let me...

Per call with Ivan, we'll use this same PR to try and simplify the 2nd half of the Versioning use case, moving low-level code blocks to its tutorial... ⏳

[shcheklein]

@jorgeorpinel good progress, but overall I feel that we moved 0.5 level, not 1 👍

What I would expect to see to make my feedback more actionable:

• Why versioning of large files is important at all. In ML or not.
• Why DVC is beneficial for this
• Give some sense how does DVC feel and look, etc. See the philosophy
• Connect with other cases

I guess, my point is that most likely we would need to write a new doc, not edit the existing one, to actually move +1 level.

[jorgeorpinel]

Understood. I'll work on rewriting it completely then ⏳

Should we merge this for now?

[jorgeorpinel]

Or should we close it in favor of #1747 ?

[shcheklein]

Or should we close it in favor of #1747 ?

@jorgeorpinel not sure I can recommend on this to be honest, it depends on your flow. From my end, it would be great to have a single PR.

[jorgeorpinel]

I think this one is done. Maybe it's not what we need but if it's an improvement and you found no errors, etc. then I would like to merge it. But we can also close it since it will be overwritten by the other PR at some point, hopefully soon.

[shcheklein]

Fine, we can merge it!

Maybe it's not what we need but if it's an improvement and you found no errors, etc

I didn't look for errors to be honest, was not reviewing it to deep since to my mind we need to redo this case on a different level.

[jorgeorpinel]

OK thanks! I think it's good to merge this because people are reading it and it's quite outdated.