docs improvements

[casperdcl]

p1

• docs: (re)structuring cml#514
• update landing page https://cml.dev
  • clear message around 2 major use cases: runner & report
    • report: basic (no DVC) & advanced (lots of integrations, e.g. Feature exp run: Dryer resume within the CI dvc#6823)
    • runner: cloud (AWS/Azure/GCP/K8s) & on-prem
  • diagrams, flowcharts, ... vis. @0x2b3bfa0's stacked crates
  • depends on cml#762
• move/expand README content in cml.dev (#718)
  • strip down & update README & redirect to website README: simplify cml#718
• update Get Started update get started #107
• put cml ci in Get Started/Usage
• put cml pr in Get Started/Usage
• dogfood dogfood cml across org cml#1109
• FAQs
  • GH: fix PR branch checkouts GitHub: checkout with head ref #252
  • ref/send-comment: PAT required for GitHub --update #253
  • Document cml send-github-check authentication #254
• sync missing command ref options docs: admonitions, fenced blocks, missing ref options #256
• Clearly separate 3 different use cases that are subsequently merged into 1 e2e example
  • CI/Git helpers (ci, pr)
  • Reporting (comment, tensorboard-dev)
    • also depends on cml#762
  • BYOC: bring-your-own-cloud/compute (runner)

p2

• update formatting (cli fenced blocks, <admon>intions) docs: admonitions, fenced blocks, missing ref options #256
• resurrect, update & move old wiki tutorials (TensorFlow MNIST GH & GL) to cml.dev
• check for old gems buried in https://github.com/iterative/cml/tree/dvc-cml
• links/references to awesome complementary GH/GL/BB features
  • cron schedule

Originally from iterative/cml#514 & @daavoo feedback

[jorgeorpinel]

update landing page

Meaning site home page? https://cml.dev/
Or docs home page? https://cml.dev/doc

TBH I'd make a separate issue just about this since it may require a pretty solid effort and maybe its not technically "documentation" (in the case of / )

[jorgeorpinel]

dogfood

Read that issue but couldn't easily understand why this is such a high priority. Some more context/ motivation here or there? 🙂

FAQs

All boxes are checked. Should the parent be checked or do we want to come up with more? ✔️

sync missing command ref options

Are we considering partial automation or a check for this? As discussed in iterative/mlem.ai#171.

[jorgeorpinel]

separate 3 different use cases... helpers... Reporting... BYOC

Does this refer to the whole structure of docs in general? (I'd also separate that into its own ticket it so.)
Have you considered making a User Guide section and move existing pages in there, organized into these sections?

Also, how does that map to the "2 major use cases: runner & report" (desired for the landing page) ? Thanks

p2

Minor, but maybe make a separate ticket too? This one in its current form seems pretty hard to ever complete 😋 up to you tho

[jorgeorpinel]

Have you considered making a User Guide section and move existing pages in there, organized into these sections?

U: Similar to this: iterative/dvc.org#4011

Also, how does that map to the "2 major use cases: runner & report" (desired for the landing page) ? Thanks

Thought about this: 2 of them map directly. But what about "CI/Git helpers (ci, pr)"? Why are they not worthy of home page mention?

Also want to note that what we mean here by "use case" is not the same as the Use Cases we have in other sites, e.g. CI/CD for ML -- which BTW I think we should consider moving into this site 🙂 (separate issue).

[casperdcl]

• user guide: IMO not required on cml.dev/doc because not enough content atm
• use cases: I think there are 2 types of "use cases" - ones with concrete 1:1 mapping to implementation (i.e. proposed use-case pages about report and runner) and ones with a bigger picture overview including multiple moving parts (cases: CI/CD for ML #350). I have no strong opinions on what to call these two types, nor where to put them, nor whether or not we need to treat them differently.