Get Started feedback and suggestions

[maxagin]

1. Why don't we use code snippets instead of just images?

2. Would expect to see the same title (correct for all the sections)

3. The section is about Available Commands, why not list all commands instead of screenshot. Anyway, user can open the Commands Palette with the link?

4. For the Plots we can mention and show screenshot, about how to toggle exp/s in the table :)

5. Déjà vu

6. I think this is important enough to show a screenshot. WDYT?

7. Very minor: helpful resources?

[maxagin]

Overall very helpful information and a well-crafted section, will study it more :). Thank you, folks!

[mattseddon]

cc @jorgeorpinel

[jorgeorpinel]

1. Why don't we use code snippets instead of just images?

• Nice to have, not critical. As of now these walkthroughs are written more as quick-read tours rather than follow-along guides. Users can go to the DVCLive (or any other linked) docs to learn how to use them and copy/paste better code from sample blocks.

2. Would expect to see the same title

• [ ] Tend to agree. Doesn't have to be 100% the same always but closer at least.

3... why not list all commands

There's a lot and they may change often. Better to let users browse them directly from the Cmd Pallette.

4... mention and show screenshot, about how to toggle exp/s in the table

• [ ] Yes. Good thing to emphasize this in the Experiments Table page.

5. "using using"

Fixed.

6... show a screenshot ("enable checkpoints" at the bottom of the Live Plot Update page).

• Meaning a code sample? Wouldn't hurt, esp. if it's an existing img. repeat (less maintenance).

Addressed.

[maxagin]

6... show a screenshot ("enable checkpoints" at the bottom of the Live Plot Update page).

Meaning a code sample? Wouldn't hurt, esp. if it's an existing img. repeat (less maintenance).

We have some difficulties explaining how the user should toggle plots in the exp table.

• [ ] This is why I suggested including a screenshot in relation to the underlined text in the IMG below (unable checkpoint).

Thank you @jorgeorpinel !

[maxagin]

Opportunity for cross-promotion which can actually be meaningful in terms of user workflow

One of the many possible options. For example, in GetStarted, after Troubleshoot & Support add Collaborate, including information on how you collaborate in DVC Studio. Message examples: a.Now you are all set up, please do not forget to learn how our DVC Studio can help you and your team to collaborate on your ML projects… b.Now you are all set up, please do not forget to create your account in DVC Studio where the collaboration on ML projects is happening

See the discussion here: https://iterativeai.slack.com/archives/C01APS0FHDM/p1658437149849249

[maxagin]

I have updated the ticked and also included the suggestion from https://github.com/iterative/vscode-dvc/issues/2373 - Update the DVC: Get Started / Plots Dashboard

[maxagin]

@jorgeorpinel please point me to the source file with the shadow we use for the images. Example below. Thank you !

I will add it to the VSCode Figma.

[maxagin]

Why don't we use code snippets instead of just images?

@shcheklein would it be the correct way to do this or there is a different way?

<pre><code>
Some code
</code></pre>

train:
  cmd: python src/train.py
  deps:
    - data/features
    - src/train.py
  params:
    - epochs
  outs
    - models/predict.h5
  metrics:
    - metrics.json:
        cash: false

[maxagin]

1   train:
2     cmd: python src/train.py
3     deps:
4       - data/features
5       - src/train.py
6    params:
7       - epochs
8     outs
9       - models/predict.h5
10     metrics:
11      - metrics.json:
12           cash: false

I am sure there is a better solution for this :)

[maxagin]

Specifying the theme an image is shown to You can specify the theme an image is displayed for in Markdown by using the HTML <picture> element in combination with the prefers-color-scheme media feature. We distinguish between light and dark color modes, so there are two options available. You can use these options to display images optimized for dark or light backgrounds. This is particularly helpful for transparent PNG images.

For example, the following code displays a sun image for light themes and a moon for dark themes:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

[shcheklein]

Specifying the theme an image is shown to @maxagin what is the source of this information? is it supported in VS Code markdown?

(overall, I think we should be fine with a single type (dark) images for now to keep it simple - less things to generate and keep taking care of)

[shcheklein]

A better solution is to use code blocks:

train:
  cmd: python src/train.py
  deps:
    - data/features
    - src/train.py
  params:
    - epochs
  outs
    - models/predict.h5
  metrics:
    - metrics.json:
        cash: false

It starts with "yaml" and end with "":

[shcheklein]

@jorgeorpinel please point me to the source file with the shadow we use for the images. Example below. Thank you !

It's here, Max: https://www.figma.com/file/hbhgEECgmGaHolFDzq7yVK/VS-Code-Walkthrough?node-id=0%3A1 - feel free to move it around to the right location.

[maxagin]

Specifying the theme an image is shown to @maxagin what is the source of this information? is it supported in VS Code markdown?

@shcheklein . Here you are: https://github.blog/changelog/2022-05-19-specify-theme-context-for-images-in-markdown-beta/