docs improvements

[casperdcl]

p1

• [x] https://github.com/iterative/cml/issues/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. https://github.com/iterative/dvc/issues/6823)
    • [ ] runner: cloud (AWS/Azure/GCP/K8s) & on-prem
  • [ ] diagrams, flowcharts, ... vis. @0x2b3bfa0's stacked crates
  • [x] depends on cml#762
• [ ] move/expand README content in cml.dev (#718)
  • [ ] strip down & update README & redirect to website https://github.com/iterative/cml/issues/718
• [x] update Get Started #107
• [ ] put cml ci in Get Started/Usage
• [ ] put cml pr in Get Started/Usage
• [ ] dogfood https://github.com/iterative/cml/issues/1109
• [x] FAQs
  • [x] GH: fix PR branch checkouts #252
  • [x] #253
  • [x] #254
• [x] sync missing command 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)
    • [x] also depends on cml#762
  • [ ] BYOC: bring-your-own-cloud/compute (runner)

p2

• [ ] update formatting (cli fenced blocks, <admon>intions) #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 https://github.com/iterative/cml/issues/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 https://github.com/iterative/mlem.ai/issues/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: https://github.com/iterative/dvc.org/pull/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 (#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.