Usage -> User Guide (initial) #382

jorgeorpinel · 2022-11-18T08:35:55Z

And moves some ex-/usage info to the cmd /ref (index page).

This is to start focusing the purpose of the different top-level pages (currently there's bits of info of everything in different places).

In review app: https://cml-dev-config-ref-ahaolkflhty.herokuapp.com/doc/user-guide

Check/merge next: ref: general clean up (code, text, links) #383

and move some info to cmd ref.

content/docs/config.md

jorgeorpinel · 2022-11-18T08:43:23Z

content/docs/config.md

-[![](/img/GitLab_CML_report.png '=400')](https://gitlab.com/iterative.ai/cml-base-case/-/merge_requests/3)
+![First CML report in GitLab](/img/GitLab_CML_report.png '=400')


Removed this link as it won't load (to the public at least):

/CC @0x2b3bfa0 please fix :)

This 404 seems to still be an issue. Maybe the URL to the MR is different or the GL project needs to be made public?

github-actions · 2022-11-18T08:43:32Z

Link Check Report

All 12 links passed!

jorgeorpinel · 2022-11-18T08:43:58Z

content/docs/config.md

-[![](/img/bitbucket_cloud_pr.png '=600')](https://bitbucket.org/iterative-ai/cml-base-case/pull-requests/2)
+![First CML report in BitBucket](/img/bitbucket_cloud_pr.png '=600')


Same.

Doesn't the link checker catch these?

/CC @0x2b3bfa0 please fix :)

content/docs/config.md

redirects-list.json

casperdcl · 2022-11-18T19:10:56Z

content/docs/config.md

-[![](/img/GitLab_CML_report.png '=400')](https://gitlab.com/iterative.ai/cml-base-case/-/merge_requests/3)
+![First CML report in GitLab](/img/GitLab_CML_report.png '=400')


/CC @0x2b3bfa0 please fix :)

casperdcl · 2022-11-18T19:11:01Z

content/docs/config.md

-[![](/img/bitbucket_cloud_pr.png '=600')](https://bitbucket.org/iterative-ai/cml-base-case/pull-requests/2)
+![First CML report in BitBucket](/img/bitbucket_cloud_pr.png '=600')


/CC @0x2b3bfa0 please fix :)

content/docs/config.md

content/docs/ref/index.md

jorgeorpinel · 2022-11-18T22:03:45Z

content/docs/ref/index.md

+
+CML provides a number of commands to help package the outputs of ML workflows
+into a CML report. These may include numeric data or model performance
+visualizations. Let's look at the typical sequence (after
+[configuration](/doc/config)):
+
+∞ `cml runner` launches a runner hosted by a cloud compute provider or
+[on-premise](/doc/self-hosted-runners).
+
+∞ `cml pr` commits a set of files to a new branch and create a pull request.
+
+∞ `cml comment` posts a Markdown report as a comment on a commit or pull/merge
+request.


This is where I moved the list of selected commands from Usage, to have something similar to https://dvc.org/doc/command-reference#typical-dvc-workflow . Of course we don't need to have the same structure or strategies as DVC docs but this one also applies, I think? There's a typical workflow (to give readers an expectation of which commands they'll probably use most).

We could update the list though, but I need help with that.

I strongly object¹ to inserting synopsis/verbose explanations/justification/problem-context into a "command reference". To me a "cmd ref" is meant to be:

closer to a "glossary" or even "index page" in a book

super concise, dry, to-the-point efficient

aimed at power-users who know exactly what they conceptually need

e.g. can't quite remember the spelling/vocab (e.g. reader is wondering "was the flag called --machine-type or --cloud-type?")

links to other more prosaic pages for fuller explanations (no inline explanations)

includes common error codes/errors/edge cases/FAQ help

And I think this should apply to all software docs sites with zero exceptions.

To be CML-specific, we need to be even more careful to keep "cmd ref" as a concise replacement for CLI --help because almost nobody will run CLI --help locally (CML is a CI tool, not a local tool)

Footnotes

based on my personal experience battling xkcd#773 scenarios ↩

Hey folks, my take on this. And I agree that it's better for us to apply same rules (or apply exception consciously for a reason that we understand).

Since here you've been discussing the index page, not actual command reference pages. I don't have a particularly strong opinion about it tbh. Practically, this page indeed can serve as an index page:

closer to a "glossary" or even "index page" in a book super concise, dry, to-the-point efficient

even its name implies this.

So, it doesn't hurt to have a table with commands. Something similar to a cheat sheet. If project doesn't have UG it might make sense to have diagrams, etc that would map all existing commands into workflow, etc.

I just don't see how that can hurt.

If we talk about specific pages inside command reference (an actual command pages). A page should have enough information to understand the semantics of an operation and what to expect from it if I run it in different ways (e.g. dvc gc - it should be clear that it collects references, removes those that are not used. It should be clear that -c affects the local cache and remote, etc, etc). The way to achieve that may be a bit different, but I would say from the most important to less important:

options and their descriptions. In some case it's fine to repeat the same sentence or two from CLI, in a lot of cases that's not enough. We should be of course trying to optimize so that both are close as much as possible (means that ppl can read less, can visit web less, etc). I just don't believe it's realistic to rely on one-two sentences there.

examples - any example, especially if it comes from a practical common problem worth a lot

description - I would expect ppl to read this less. Arguably this can become a part of UG, or something else.

Command reference in my head maps to a man page, to pages like this - https://git-scm.com/docs/git-checkout

Some major misconceptions here:

self-contained UI manuals [...] clig.dev [...] terminal-based documentation

This is completely inapplicable to CML, which effectively does not have terminal-based docs.¹ It is far more akin to Studio - users only interact with it online. Basically this:

apply exception consciously for a reason that we understand

Secondly and more importantly, why should we delete content where a reasonable end-user needs it most?

Footnotes

no reasonable end-user has ever run cml ... --help ↩

inapplicable to CML, which effectively does not have terminal-based docs

Good point. Let's keep that in mind but still the web format allows us more flexibility (no need to keep refs super dry IMO).

and proper warning admons

from Config guide Per #382 (review)

jorgeorpinel

too many changes in this PR. Could we please split this?

The only change unrelated to the PR purpose was to the comment command, which has now been moved to #383. Everything else comes from the existing Usage page, being turned into a User Guide section now.

Recap of changes 👇🏼

jorgeorpinel · 2022-12-16T00:38:29Z

content/docs/ref/comment.md

 ## Examples

+### Post a text report
+
+Write to your report using whatever method you prefer. For example, copy the
+contents of a text file containing the results of ML model training:
+
+```cli
+$ cat results.txt >> report.md
+```
+
+### Post a graphic report
+
+Display images using Markdown or HTML. Note that if an image is an output of


Moved here from https://cml.dev/doc/usage#cml-reports

please revert

jorgeorpinel · 2022-12-16T00:39:00Z

content/docs/ref/index.md

 # Command Reference

+CML provides a number of commands to help package the outputs of ML workflows
+into a CML report, which may include numeric data or model performance
+visualizations. Let's look at the typical sequence (after
+[configuration](/doc/user-guide)):


Moved here from https://cml.dev/doc/usage#cml-commands

can we move it back?

@casperdcl don't we need some content in the cmd ref index though? Currently it's empty except for a Generic Options section. Seems a little bare. Imagine a user lands in this page as their entry point to the docs site (per analytics this does happen sometimes) or as one of the first pages visited. It should give some general info on cml commands as a whole, link to GS or Usage, etc., I think.

Granted, this could be addressed separately and/or we can repeat the text above in you prefer to also keep this general guidance in the Usage (now UG index) page. Lmk

please revert

jorgeorpinel · 2022-12-16T00:41:17Z

content/docs/user-guide/index.md

-# Using CML
+# User Guide: Introduction

 A GitLab, GitHub, or Bitbucket account is required. Familiarity with


Repurposed (simplified) much of this doc as the new UG index page

jorgeorpinel · 2022-12-16T00:41:36Z

content/docs/sidebar.json

+        "label": "CML with DVC",
+        "slug": "cml-with-dvc"
+      },
+      {
+        "label": "Self-hosted Runners",
+        "slug": "self-hosted-runners"


Moved these 2 existing docs into the (new) UG section

redirects-list.json

shcheklein · 2022-12-16T03:03:30Z

@jorgeorpinel thanks for cleaning this up!

Now, @casperdcl @jorgeorpinel my biggest question is - how this page https://cml-dev-config-ref-ahaolkflhty.herokuapp.com/doc/user-guide is different from the three pages here https://cml-dev-config-ref-ahaolkflhty.herokuapp.com/doc/start/github (+gitlab and +bb).

I think we need to agree on that first if we are touching this structure at all (which I would not consider that critical tbh).

My 2cs on this:

Existing Get Started index should be dissolved into the Home page and into "What is CML?" (can be part of UG or a global page)
The new UG index page serves better to become a new GS index page. It's already a quick start to some extent and it deserves to be at the beginning of the flow. If people need more details they can read GH, GL, BB sections in GS.

casperdcl · 2022-12-19T21:39:18Z

how this page cml-dev-config-ref-ahaolkflhty.herokuapp.com/doc/user-guide is different from the three pages here cml-dev-config-ref-ahaolkflhty.herokuapp.com/doc/start/github (+gitlab and +bb).

@shcheklein my intended target audiences (implied by the cards at https://cml.dev/doc) are:

/doc/start pages: beginners to CI/CD
- I want to change them to use tabs, but that's out of scope for this PR
/doc/usage: intermediate/experienced users of CI/CD but new to CML reports
/doc/cml-with-dvc: intermediate/experienced users of DVC but new to CML reports
/doc/self-hosted-runners: advanced users of CI/CD but new to CML runners (cloud and/or on-premise)

So I feel we're losing target audiences if we move pieces of content and/or dissolve pages.

To me 100% of the changes in this PR harm the funnel.

shcheklein · 2022-12-19T22:00:02Z

Thanks @casperdcl

It's not enough though to state the expectation, it should be clear to people and they should be reading it in the way you expect them to read. This is my biggest concern with the current structure (even I'm getting lost from time to time as I mentioned a few times - which of the pages to take to copy paste? which way to install to pick, etc).

I would be surprised if anyone can understand that start is for beginners and usage is for more advanced. Both of them are "get started/quick start"-kinda material and are hard to differentiate. If we want to keep it this way - let's be very explicit about this, in the text and in the name.

Also, I still think it can be a single section, page that covers both. Starts with the assumption that people are familiar with CI/CD and provides more details below, referencing them explicitly.

^^ this is primarily about the landing page + install button + get started + usage.

I'm fine with DVC and self-hosted runners. Clearly here we can debate only if we need an extra layer or not. I don't have a strong opinion on that and totally fine with either. I doubt that change like this hurts anything. Though, in the current state of the project we can do w/o an extra layer.

casperdcl · 2022-12-19T22:06:06Z

@shcheklein I fully agree.

To me a gewd action plan might be:

rename /doc/start to "Intro to CI/CD and CML reports"
rename /doc/usage to "Intro to CML reports"

move some existing content from (1) to (2), then write some more appropriate content in (1).

About landing page + install, yes we should fix that too (but separate issues, right? Probably #250 and #404)

shcheklein · 2022-12-19T22:29:21Z

Hmm, it sounds too complicated to me still.

Even if you read the names:

Intro to CI/CD and CML reports
Intro to CML reports

They overlap, which one should I read if I'm familiar with CI/CD more or less? It's already a sign that something is wrong here.

And improve `comment` ref.

jorgeorpinel · 2022-12-27T17:47:24Z

how this page (UG: Intro) is different from the three pages here (GS) ?
touching this structure ... I would not consider that critical

Good Q but this is an existing problem (see current Usage page). Except that it's worst rn, since it also tries to cover configuration, command reference, etc. It's messy (originally intended as a cheat sheet, I think).

This PR essentially cleans that up, which is intended as a step in the right direction. For example, this allowed us to identify the clear overlap with the GS and have this discussion.

Get Started index should be dissolved...
UG index to become a new GS index page (If people need more details they can read GH, GL, BB pages)

Yep, that could work 👍🏼

intended target audiences

Nice intentions but the content does not currently reflect that. E.g. the Usage page is as introductory as the GS (as @shcheklein points out). Also, we have an official framework for docs, which is what I'm following.

About landing page + install, yes we should fix that too (but separate issues, right?

Agree. Let's address as a follow-up.

100% of the changes in this PR harm the funnel.

Confused by this 😕. We have been discussing these change in different places for some time. You even suggested some of them specifically from what I remember, @casperdcl (e.g. call the page "User Guide: Introduction").

Regardless, these changes are not major (just a stepping stone) and hardly hurt anything. I wish we could be more nimble and move fwd.

Should we set up a call?

These changes pertain to #382 .

Outdated, I think.

jorgeorpinel

Apparently I had some pending comments here. Let's see what they are 👇🏼

U: Nothing is still relevant.

content/docs/ref/comment.md

jorgeorpinel · 2023-02-24T04:44:37Z

I can no longer push to this repo but I've solved the conflicts in my branch. I set up a fork so this PR can be reopened in https://github.com/iterative/cml.dev/compare/master...jorgeorpinel:cml.dev:config--ref?expand=1 if needed. Thanks

shcheklein · 2023-02-25T17:01:43Z

@jorgeorpinel I gave the access back, please feel free to resolve and let's redeploy the branch to make the final decision on this.

jorgeorpinel · 2023-03-08T04:49:23Z

Thanks @shcheklein . Done

github-actions · 2023-03-08T04:56:54Z

Link Check Report

All 11 links passed!

shcheklein · 2023-03-09T04:22:19Z

@jorgeorpinel I see the intention, and sorry for asking you to resolve the conflict. I've decide to close this PR, can't focus now on this, and I don't think it changes the dynamics for (now not so complicated) docs structure in CML. I think it's fine to have everything on the top level for now. If you feel there were some improvements / fixes besides the structure changes - please let's move the into a separate PR. Thanks for the effort!

jorgeorpinel · 2023-03-11T03:36:32Z

No worries. There are some minor things. Extracted to #450.

guides: rename Usage->Config and

ae23976

and move some info to cmd ref.

jorgeorpinel added the documentation Markdown files label Nov 18, 2022

jorgeorpinel requested a review from a team November 18, 2022 08:35

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 18, 2022 08:36 Inactive

redirect /usage -> /config

4b08551

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 18, 2022 08:39 Inactive

jorgeorpinel marked this pull request as ready for review November 18, 2022 08:40

jorgeorpinel requested a review from a team as a code owner November 18, 2022 08:40

jorgeorpinel changed the title ~~Usage->Config~~ Usage -> Config Nov 18, 2022

jorgeorpinel commented Nov 18, 2022

View reviewed changes

content/docs/config.md Outdated Show resolved Hide resolved

jorgeorpinel commented Nov 18, 2022

View reviewed changes

content/docs/config.md Outdated Show resolved Hide resolved

jorgeorpinel commented Nov 18, 2022

View reviewed changes

redirects-list.json Show resolved Hide resolved

jorgeorpinel mentioned this pull request Nov 18, 2022

ref: general clean up (code, text, links) #383

Closed

casperdcl previously requested changes Nov 18, 2022

View reviewed changes

casperdcl assigned jorgeorpinel Nov 18, 2022

jorgeorpinel changed the title ~~Usage -> Config~~ Usage -> Config (maybe) + related updates Nov 18, 2022

Merge branch 'master' into config--ref and

f70bf8e

and proper warning admons

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 24, 2022 06:42 Inactive

guide: fix image links again (in captions)

d7dbc4e

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 24, 2022 06:51 Inactive

guide: put example repos back in main tabs (Config)

42cd4ff

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 24, 2022 07:01 Inactive

ref: bring comment-create details & examples

82b74d5

from Config guide Per #382 (review)

shcheklein temporarily deployed to cml-dev-config-ref-mipoc3rfgb7 November 24, 2022 07:16 Inactive

jorgeorpinel requested a review from casperdcl November 24, 2022 07:24

jorgeorpinel changed the title ~~Usage -> Config (maybe) + related updates~~ Usage -> User Guide (initial) Nov 25, 2022

jorgeorpinel added the C: guide Content of /doc/user-guide label Nov 25, 2022

jorgeorpinel commented Dec 16, 2022

View reviewed changes

jorgeorpinel requested review from shcheklein and removed request for casperdcl December 16, 2022 00:46

Merge branch 'master' into config--ref and

f862dfe

And improve `comment` ref.

shcheklein temporarily deployed to cml-dev-config-ref-ahaolkflhty December 27, 2022 17:11 Inactive

jorgeorpinel added a commit that referenced this pull request Dec 27, 2022

usage: roll-back (1/2)

735bd2b

These changes pertain to #382 .

jorgeorpinel added a commit that referenced this pull request Dec 27, 2022

usage: roll-back changes pertaining to #382

5dac605

casperdcl self-assigned this Feb 14, 2023

jorgeorpinel unassigned casperdcl Feb 20, 2023

jorgeorpinel commented Feb 24, 2023

View reviewed changes

Merge branch 'master' into config--ref

986736e

jorgeorpinel removed their assignment Feb 24, 2023

roll back unknown changes

2a4e24e

Roll back unrelated change

84db09c

shcheklein temporarily deployed to cml-dev-config-ref-uz0nzru4ibv March 8, 2023 04:50 Inactive

shcheklein closed this Mar 9, 2023

jorgeorpinel mentioned this pull request Mar 11, 2023

Usage: improvements #450

Merged

		[![](/img/GitLab_CML_report.png '=400')](https://gitlab.com/iterative.ai/cml-base-case/-/merge_requests/3)
		![First CML report in GitLab](/img/GitLab_CML_report.png '=400')

		[![](/img/bitbucket_cloud_pr.png '=600')](https://bitbucket.org/iterative-ai/cml-base-case/pull-requests/2)
		![First CML report in BitBucket](/img/bitbucket_cloud_pr.png '=600')

Usage -> User Guide (initial) #382

Usage -> User Guide (initial) #382

Conversation

jorgeorpinel commented Nov 18, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Nov 18, 2022 • edited

Link Check Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

jorgeorpinel Nov 18, 2022 • edited

Choose a reason for hiding this comment

casperdcl Nov 24, 2022 • edited

Choose a reason for hiding this comment

Footnotes

This comment was marked as resolved.

This comment was marked as resolved.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Footnotes

Choose a reason for hiding this comment

jorgeorpinel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

casperdcl Dec 19, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shcheklein commented Dec 16, 2022

casperdcl commented Dec 19, 2022 • edited

shcheklein commented Dec 19, 2022

casperdcl commented Dec 19, 2022 • edited

shcheklein commented Dec 19, 2022

jorgeorpinel commented Dec 27, 2022 • edited

jorgeorpinel left a comment • edited

Choose a reason for hiding this comment

jorgeorpinel commented Feb 24, 2023 • edited

shcheklein commented Feb 25, 2023

jorgeorpinel commented Mar 8, 2023

github-actions bot commented Mar 8, 2023

Link Check Report

shcheklein commented Mar 9, 2023

jorgeorpinel commented Mar 11, 2023

jorgeorpinel commented Nov 18, 2022 •

edited

github-actions bot commented Nov 18, 2022 •

edited

jorgeorpinel Nov 18, 2022 •

edited

casperdcl Nov 24, 2022 •

edited

casperdcl Dec 19, 2022 •

edited

casperdcl commented Dec 19, 2022 •

edited

casperdcl commented Dec 19, 2022 •

edited

jorgeorpinel commented Dec 27, 2022 •

edited

jorgeorpinel left a comment •

edited

jorgeorpinel commented Feb 24, 2023 •

edited