search

iterative / cml.dev

🔗 CML website and documentation
https://cml.dev
Apache License 2.0
12 stars 23 forks source link

Usage -> User Guide (initial) #382

Closed jorgeorpinel closed 1 year ago

jorgeorpinel commented 1 year ago

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

github-actions[bot] commented 1 year ago

Link Check Report

All 12 links passed!

shcheklein commented 1 year ago

@jorgeorpinel there are too many changes in this PR. Could we please split this?

(There was probably a discussion also) I'm also not sure why/if Usage should become a User Guide.

casperdcl commented 1 year ago

there are too many changes in this PR

yes I agree; would be much quicker to discuss & merge in at least some bits of this if you could split it up.

shcheklein commented 1 year ago

@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:

casperdcl commented 1 year ago

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:

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 commented 1 year ago

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 commented 1 year ago

@shcheklein I fully agree.

To me a gewd action plan might be:

  1. rename /doc/start to "Intro to CI/CD and CML reports"
  2. 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 commented 1 year ago

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.

jorgeorpinel commented 1 year ago

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?

jorgeorpinel commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

Thanks @shcheklein . Done

github-actions[bot] commented 1 year ago

Link Check Report

All 11 links passed!

shcheklein commented 1 year ago

@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 commented 1 year ago

No worries. There are some minor things. Extracted to https://github.com/iterative/cml.dev/pull/450.