cases: generalized shared dev server

[jorgeorpinel]

From #637 (review)

1. Do we need blog-like articles in a semi-static website? UPDATE: We even have a blog now...
   How about extracting the more user manual-like information from the existing use cases into user guides and write actual articles to replace our use cases? These can be published in our blog, Medium, etc. (handled like a devrel matter like any other article).

UPDATE: Jump to summary: #654 (comment)

---

OUTDATED:

2. by "use case" we really mean "case studies" - these are actual (mini) guides with some steps to address specific scenarios. A "use case" is a more general problem solved by the system, they typically map directly to features in a system, so really the current some of the [User Guide](https://dvc.org/doc/user-guide docs are closer to actual use cases in my understanding.

   

Related to #425; Could work on them together 🙂

[jorgeorpinel]

Some comments from @shcheklein:

From #637 (review) (regarding the list of guides in /user-guide/index.md)):

I hope that we'll have a proper third level soon to cluster some of these by topics. Not for this PR for sure...

From #637 (comment) (regarding reorganizing "External Data" guides)
UPDATE: Moved to #566 (comment)

From #637 (comment):

Regarding the User Guide - there are sections like "Large Files Optimization" - it's not a use case by itself, it's a technical description how to fine fine tune DVC in certain situations. I think UG should include things like Pipelines -> How to Edit, How to Create, etc. And Updating Tracked Files is very similar in my mind to those.

[jorgeorpinel]

Just found a good example of something closer to my definitions of use case vs. case study

• A "use case" is a more general problem solved by the system...
• (Currently) by "use case" we really mean "case studies"... address specific scenarios.

See https://www.hashicorp.com/products/terraform:

vs.

Except here, case studies are actual real-life "success stories", told in hindsight (explaining how the tool was used).

[shcheklein]

@jorgeorpinel exactly, that's why I don't the "case study" term - it's has a very well defined meaning - a real-life "success story".

Terraform use cases (with some adjustment that they are not published in the docs) look more or less as what we are trying to do with our Use Cases. Our cases a bit lower level since they are part of the docs, but the idea is the same. The should be describing a high level problem, then a high level solution (with links to the implementation details).

[shcheklein]

The main point here is that our Use Cases should not feel like tutorials. I think it's fine to give some examples, or some code snippets, but mostly the should be focused around the problem. Thus for example we have images, but we never did them executable.

Our user guide is very far from describing use cases.

[jorgeorpinel]

I agree that "case study" is not the best term and that our first 2 use cases could be seen as high-level enough. I guess it's just the last one, https://dvc.org/doc/use-cases/shared-development-server, that I don't see as a use case. This one I would still recommend to get out the docs into a blog post perhaps. I think it's too specific, not a general problem that DVC as a product is designed to solve, just something you happen to be able to setup with DVC.

I would also rename the 2nd one "Sharing Data and Model Files" (using infinitive tense).

Same for "Updating Tracked Files" in the user guide (for consistency). Added to #720.

[shcheklein]

@jorgeorpinel agreed. Sharing dev server probably should be renamed and generalized into - resource optimization or something similar. It's definitely stands out. But we need to come up with a better name place for it.

[jorgeorpinel]

Summary of discussion above

How about extracting the more user manual-like information from https://dvc.org/doc/use-cases/shared-development-server into user guides and write actual articles to replace our use cases? These can be published in our blog, Medium, etc. (handled like devrel [material])
I think it's too specific, not a general problem that DVC as a product is designed to solve, just something you happen to be able to setup

agreed. Sharing dev server probably should be renamed and generalized into - resource optimization or something similar
our Use Cases should not feel like tutorials. I think it's fine to give some examples, or some code snippets, but mostly the should be focused around the problem. Thus for example we have images

[jorgeorpinel]

Note: also https://dvc.org/doc/user-guide/managing-external-data#how-external-outputs-work shouldn't link to https://dvc.org/doc/use-cases/shared-development-server#configure-the-external-shared-cache for external cache instructions, since

1. those are general instructions that don't belong (exclusively) in Use Cases, and
2. shared external caches are not good for external outputs (see support adding/transfering data straight to cache/remote  dvc#4520 (comment)).