Dvc.org: use-cases: extract shared-development-server into actual article?

[jorgeorpinel]

From https://github.com/iterative/dvc.org/pull/637#pullrequestreview-293443095

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: https://github.com/iterative/dvc.org/issues/654#issuecomment-738557458

---

OUTDATED:

1. 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 https://github.com/iterative/dvc.org/pull/637#pullrequestreview-293500033 (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 https://github.com/iterative/dvc.org/pull/637#discussion_r329336744 (regarding reorganizing "External Data" guides)
UPDATE: Moved to https://github.com/iterative/dvc.org/issues/566#issuecomment-536859662

From https://github.com/iterative/dvc.org/pull/637#discussion_r329337401:

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

[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