Add references to VS Code for DVC plots

[dberenbaum]

Report

Some places where it would help:

https://dvc.org/doc/command-reference/plots

This might be odd in a CLI ref, but for example, the current docs say:

DVC generates plots as static HTML webpages that can be open with a web browser. They can also be saved as SVG or PNG image files from the browser.

Seems like it would be useful to at least mention that they can be visualized in VS Code, since it's a better experience than the static HTML.

https://dvc.org/doc/start/data-management/metrics-parameters-plots

https://dvc.org/doc/start/experiments/visualization

@jorgeorpinel @shcheklein Thoughts?

[shcheklein]

Yes, 💯 , I agree.

[shcheklein]

@jorgeorpinel could you take this one?

[jorgeorpinel]

Sure. I started working on it and left this follow-up Q from #3718 (comment):

... do we add Studio links in all (or most) places where VS Code is linked from? Or just the plots-related ones for now (i.e. in the same PR) ? Lmk

https://dvc.org/doc/start/data-management/metrics-parameters-plots
https://dvc.org/doc/start/experiments/visualization

BTW I added it to the parent pages for now (see PR). Do we want to repeat it in those specific sub-pages too? (Note the whole Get Started needs yet another reorg...)

[jorgeorpinel]

Continuing discussion from #3735 (comment):

For visualizing plots or experiments, we may want to treat VS Code as a first-class option and integrate them more seamlessly into the docs...

1. From https://dvc.org/doc/command-reference/plots ... mention that plots can be visualized in VS Code, Studio, or static HTML. Static HTML feels like an option of last resort now
2. A lot of https://dvc.org/doc/user-guide/experiment-management/comparing-experiments could be skipped by a user if they use VS Code
3. In https://dvc.org/doc/start/experiments/visualization, it's not that clear how these plots are useful... Showing the image alongside other plots or compared to other experiments in VS Code could help clarify

@dberenbaum these are great points. I'm just not sure whether we want to present the extension as part of DVC that transparently, when it's not really the same thing (I don't mean technically, but based on the current user experience). It's a GUI for DVC, which you still have to install separately. Rn you see this confusion in user questions like "what's the difference between DVC and the extension"?

Probably a question for @mattseddon as well. We should try to decide sooner than later how should we present the extension? How do we separate and/or mix its docs with DVC's ? Thanks

[jorgeorpinel]

We should try to decide sooner than later how should we present the extension? How do we separate and/or mix its docs with DVC's ?

p.s. same question for @tapadipti wrt Studio. With the difference that Studio does have it's own docs (and quite extensive at this point). Thanks

[mattseddon]

Probably a question for @mattseddon as well. We should try to decide sooner than later how should we present the extension? How do we separate and/or mix its docs with DVC's ? Thanks

In order to answer the question we should break up users into 4 different groups:

1. Pre-existing DVC users, who use VS Code
2. Pre-existing DVC users, who have never used VS Code
3. New DVC users who have never used VS Code
4. New DVC users who use VS Code

The extension is a visual product and should need minimal documentation. I would hold off on doing things like presenting screenshots because they are going to become stale quickly. IMO the DVC docs should be driving users in group 1 & 2 towards some kind of easy trial of the extension. We'll be working on improve the trial process/time to value as part of the extension onboarding experience (one of our focuses/big stories for Q3). Personally, I think that we should initially focus on group 4 (new to DVC but not VS Code). Once we have that nailed down we can start to cater for the other 3 groups (probably prioritise 3).

[dberenbaum]

p.s. same question for @tapadipti wrt Studio. With the difference that Studio does have it's own docs (and quite extensive at this point). Thanks

I don't think Studio has quite the same considerations because it's a commercial product intended to provide distinct value across multiple products.

[jorgeorpinel]

I also have a feeling that it looks like an add.... in terms of how useful it is and how disruptive it is in the document

@shcheklein I think that for the DVC Get Started that's what we were shooting for (an ad). If we're mainly concerned about the current style, we can use simple <admon type="note">s without 🔥 icons.

For the cmd ref or guides around visualization, I suppose we can integrate the extension mentions a bit more (without admonitions). Again, if this is mainly about the styling/readability, then it's something we can address quickly -- I was more worried about larger implications (on all DVC docs) of treating the extension as part of DVC (see discussion above).

[shcheklein]

@jorgeorpinel tbh, I would remove them completely - they are noisy:

... and do look like an ad since Studio is a commercial product.

I liked some examples as Dave mentioned in the PR. I'm open to discuss any other ideas.

I also agree that we should not treat Studio and VS Code the same.

[tapadipti]

I don't think Studio has quite the same considerations because it's a commercial product intended to provide distinct value across multiple products.

Agree with @dberenbaum. Studio works across multiple products, not just DVC.

[jorgeorpinel]

I'm still not sure what's wrong with advertising our own products in our own sites (which generate relevant traffic), but I'm removing most admonitions in #3783 for now.

[jorgeorpinel]

Addressing this issue on top of that in #3784.

[jorgeorpinel]

any other places? (plots, table of experiments, even data? #3784 (comment)
I'm sure we could do more, but this is a really nice start #3784 (comment)

Feel free to reopen this ticket with a few more specific ideas of places to add VS Code Plots Dashboard mentions to. Thanks