DVCLive: Revisit docs organization and content

[daavoo]

Closes https://github.com/iterative/dvclive/issues/273 Closes https://github.com/iterative/dvclive/issues/289

Try to focus on the simplest case: Use existing ML integration alongside DVC.

The previous state jumped directly into the API overview and addressed DVC integration on a separate page. Try to better reflect the high-level steps required to get everything running in the most common case.

[github-actions[bot]]

Link Check Report

• content/docs/dvclive/api-reference/index.md

  • PASS: /doc/dvclive/ml-frameworks = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/ml-frameworks (200)
  • PASS: /doc/dvclive/api-reference/live = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live (200)
  • PASS: /doc/dvclive/outputs = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/outputs (200)
  • PASS: /img/dvclive-html.gif = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/img/dvclive-html.gif (200)
  • PASS: /doc/dvclive/api-reference/live#parameters = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live#parameters (200)

• content/docs/dvclive/get-started.md

  • PASS: /doc/dvclive/ml-frameworks = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/ml-frameworks (200)
  • PASS: /doc/dvclive/api-reference = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference (200)
  • PASS: /doc/dvclive/outputs = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/outputs (200)
  • PASS: /doc/user-guide/experiment-management/running-experiments = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/user-guide/experiment-management/running-experiments (200)
  • PASS: /docs/dvclive/api-reference#metrics-report = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/docs/dvclive/api-reference#metrics-report (200)
  • PASS: /img/dvclive-html.gif = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/img/dvclive-html.gif (200)
  • PASS: https://marketplace.visualstudio.com/items?itemName=Iterative.dvc (200)
  • PASS: https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/experiments-table.md (200)
  • PASS: https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/plots.md (200)
  • PASS: https://github.com/iterative/vscode-dvc/raw/main/extension/resources/walkthrough/images/experiments-table.png (200)
  • PASS: https://github.com/iterative/vscode-dvc/raw/main/extension/resources/walkthrough/images/plots-trends.png (200)
  • PASS: /doc/studio = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/studio (200)
  • PASS: /doc/studio/user-guide/projects-and-experiments/visualize-and-compare = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/studio/user-guide/projects-and-experiments/visualize-and-compare (200)
  • PASS: /img/dvclive-studio-plots.png = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/img/dvclive-studio-plots.png (200)

• content/docs/dvclive/ml-frameworks/mmcv.md

  • PASS: https://github.com/open-mmlab/mmcv/blob/master/mmcv/runner/hooks/logger/dvclive.py (200)
  • PASS: https://github.com/open-mmlab (200)

• content/docs/dvclive/ml-frameworks/tensorflow.md

  • PASS: /docs/dvclive/ml-frameworks/keras = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/docs/dvclive/ml-frameworks/keras (200)

• content/docs/dvclive/outputs.md

  • PASS: /doc/dvclive/api-reference/live = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live (200)
  • PASS: /doc/dvclive/api-reference/live/log = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live/log (200)
  • PASS: /doc/dvclive/api-reference/live/log_image = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live/log_image (200)
  • FAIL: /doc/dvclive/api-reference/live/log_param = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live/log_param (404)
  • PASS: /doc/dvclive/api-reference/live/log_plot = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live/log_plot (200)
  • PASS: /doc/dvclive/api-reference/live/make_report = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live/make_report (200)

• content/docs/dvclive/resume.md

  • PASS: /doc/user-guide/experiment-management/checkpoints = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/user-guide/experiment-management/checkpoints (200)
  • PASS: /doc/dvclive/api-reference/live#parameters = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/dvclive/api-reference/live#parameters (200)
  • PASS: /doc/user-guide/project-structure/pipelines-files#output-subfields = https://dvc-org-dvclive-refacto-czwjzz.herokuapp.com/doc/user-guide/project-structure/pipelines-files#output-subfields (200)

1/31 links failed.

[shcheklein]

I think ppl will start with an existing framework (not an index page of the API). We should be prepared for that as much as we can. Let's say I use Keras and I start from the Keras integration page - how many other pages I'll have to read to get to a working project that I can understand? That's the metric we should be optimizing in the docs here.

Probably, it means that we can even introduce some duplication and / or clear 1-2-3 where 2 and 3 are links to some general pages (dvc.yaml , code sinppet with DVCLive, etc).

[daavoo]

I think ppl will start with an existing framework (not an index page of the API). We should be prepared for that as much as we can. Let's say I use Keras and I start from the Keras integration page - how many other pages I'll have to read to get to a working project that I can understand? That's the metric we should be optimizing in the docs here

I was thinking people start from Get Started, but will try to also optimize for this case.

Probably, it means that we can even introduce some duplication and / or clear 1-2-3 where 2 and 3 are links to some general pages (dvc.yaml , code sinppet with DVCLive, etc).

I updated Get Started and moved the old one to API Reference. I tried to make the current Get Started a step-by-step with links to more details. Do you think the step-by-step should also be present on each ML Framework page?

[shcheklein]

so, concept of loggers is more or less clear and familiar I guess, that's why last time I was trying I went right to the Keras page ... I expected to see a simple copy-paste to get started

Get started itself is good for beginners I think in this case.

Do you think the step-by-step should also be present on each ML Framework page?

I think it would benefit a lot if we make those pages self-containable + easy way to copy paste w/o jumping around and get decent results.

[jorgeorpinel]

I think ppl will start with an existing framework

I was thinking people start from Get Started

Here are top entry pages for DVCLive now:

Looks like frameworks and DVC integration trump the Get Started quite a bit. And for the DVCLive docs home page (top entry page) most traffic comes from Google (mainly direct tool name searches):

Top queries:

It's also interesting that / is listed among top entry pages (first figure). Maybe we should add a direct link to DVCLive in the site home page? If so let's comment in #3833

Should've probably discussed and planned in https://github.com/iterative/dvclive/issues/273 first (sorry I didn't notice it earlier) but let's check this PR since we have it!

[jorgeorpinel]

Hi 🙂

Seems like this may go stale soon. Feel free to break this up into more than one PR so we can get some "less controversial" changes merged @daavoo (if that helps).

Thanks

[daavoo]

Hi 🙂

Seems like this may go stale soon. Feel free to break this up into more than one PR so we can get some "less controversial" changes merged @daavoo (if that helps).

Thanks

Apologies, I open the P.R. as a side task for the sprint but then I didn't find the time to address the comments.

[jorgeorpinel]

Not a problem. I just like to check in on inactive PRs now and then. Eventually we'll have to split and merge, or close it for now. No rush though, please prioritize as needed for the product.

[github-actions[bot]]

5bf3d8e

Link Check Report

There were no links to check!

[dberenbaum]

Looks really good overall! Mostly need to figure out the resume/checkpoints content and refine the dvc integration a little.