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]

And maybe even rename User Guide to User Manual? Same concept but a little better naming because we can call each document inside a "guide" without causing confusion with the parent section (the manual).

Extracted to #720

[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.

[dashohoxha]

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.

Another option is to describe a Use Case (or Case Study or whatever we call them) as an interactive Katacoda example (if this is possible). A working concrete example is easier to understand than wordy explanations with hypothetical situations.

[shcheklein]

Online interactive tutorials are complimentary and are not replacements for "wordy explanations". They make it easier things to run, sometimes easier to understand. But they still require explanations around them - motivation, what's happening, etc.

[jorgeorpinel]

We definitely want interactive tutorials also, but the case studies are not meant to be that detailed. They contain real-life problems but don't provide exact end-to-end commands to solve them (which would make the documents longer as well as harder to maintain). They just show the core actions and DVC commands needed to address a class of problems. At least this is how Use Cases are designed at the moment.

[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).