[discussion] New page(s): docs

[casperdcl]

Proposal. Discussion for @iterative/cml & @iterative/docs:

• A new docs page at a subdomain (the "Docs" link in the cml.dev hero/header should go to https://doc(s).cml.dev which should have a similar layout to https://dvc.org/doc).
• In addition, we need subpages. All pages should have a ToC.

Proposed layout:

• doc(s).cml.dev/ CML Documentation
  • /features/ Features
  • /start/ Getting Started
    • /start/github/ Getting Started with GitHub
    • /start/gitlab/ Getting Started with GitLab
  • /guide/ User Guide
  • /ref/ Command Reference
    • /ref/#pr cml-pr
    • /ref/#send-comment cml-send-comment
    • /ref/#tensorboard-dev cml-tensorboard-dev
    • ... etc ...

[0x2b3bfa0]

Would you mind renaming some paths for consistency with dvc.org? Or, alternatively, renaming the dvc.org ones if you feel revolutionary. 😄

• doc/features ➔ doc/use-cases like in dvc.org/doc/use-cases
• doc/guide ➔ doc/user-guide like in dvc.org/doc/user-guide
• doc/ref ➔ doc/command-reference like in dvc.org/doc/command-reference

[0x2b3bfa0]

I assume that the use cases section will contain brief descriptions of the problems that CML solves and high-level descriptions of how it solves them, not something similar to "use cases" like this.

[casperdcl]

Yes @0x2b3bfa0 (and @iterative/cml & @iterative/docs) I'll repurpose this issue as a place for discussion (@rogermparent & @julieg18 feel free to unsubscribe here. I've opened a separate iterative/dvc.org#56 for actual implementation).

[casperdcl]

Would you mind renaming some paths for consistency with dvc.org

nooo!

Or, alternatively, renaming the dvc.org ones if you feel revolutionary. 😄

yess!

I assume that the use cases section will contain brief descriptions of the problems that CML solves and high-level descriptions of how it solves them

yess!

[0x2b3bfa0]

/doc/ref/#{command}

Would doc/ref be a single page with multiple uniquely identified headings?

Explanations for some of the commands could become a bit lengthy for a single page. Why not use /doc/ref/{command} to leave room for additional information?

[casperdcl]

Explanations for some of the commands could become a bit lengthy for a single page.

Maybe. For now there didn't seem to be that much written and I would still rely on the nav/ToC to list all the commands, but sure, could have separate pages as per dvc.org's refs.

[jorgeorpinel]

/doc/features/ Use Cases

So are these features or use cases? Also keep in mind it's not clear Use Cases are documentation, we've been talking about moving them directly to dvc.org/use-cases for some time so maybe you want to do that from the beginning in cml.dev?

I agree about consistent path naming vs dvc.org. I incline for slightly longer paths if they're more descriptive (may also help in SEO). So use-cases ("cases" could refer to other things), start, guide (descriptive enough in this case), and command-reference or at least cmd-ref (keep in mind dvc.org also has an API ref section).

[casperdcl]

So are these features or use cases?

I use these terms interchangeably. Related: iterative/dvc.org#144 (comment)

merge [/cases] with /features and /

and

We desperately need to have a list of things which we consider synonymns because otherwise the language barrier seems to be the biggest problem when communicating with each other.

also FYI @shcheklein's intention was to have dvc.org's "Use Cases" to be what I think you label "Features." I think to avoid confusion I'm going to stop using the term "use cases" forever because it is clearly too ambiguous to be fit for purpose.

I agree about consistent path naming vs dvc.org

For once I don't agree on a consistency point. As we start from a blank slate, this project should do things perfectly unencumbered by problems in sister repos. As far as I can tell dvc.org will be shifting to the proposed cml.dev layout (which is why I propose it. It's also only subtly different.) dvc.org will take some time to shift because it's so large 🐘 but that doesn't mean we need to duplicate the effort in cml.dev.

Heck I just thought of an even better idea. Subdomains. doc(s).cml.dev/start is infinitely superior to (www.)cml.dev/doc(s)/start. Updated the description accordingly.

I incline for slightly longer paths if they're more descriptive

I fully absolutely agree, but fail to see docs.cml.dev/command-reference/#cml-publish as more descriptive than doc.cml.dev/ref/#publish. Would like to get feedback on this.

keep in mind dvc.org also has an API ref section

So what? Doesn't affect cml.dev's layout. ⚔️

[shcheklein]

A few points:

doc.cml.dev

We decided to keep it conservative for dvc.org. cml.dev/doc (most likely, and would not risk it w/o a very strong reason) is better for search engines (one domain cml.dev vs two)

The approach we take is docs should always be v0 (i.e. never non-breaking) I think.

Agreed, that seems what we have been doing. Though we had a lot of discussions and lot of push to implement versioning. During the last release we managed to do this by marking new features available since 2.0. I personally prefer this better - simpler to manage, one place to update. It might be beneficial to freeze previous versions though and being able to deliver them as pdf at least? (some relevant tickets iterative/gatsby-theme-iterative#35 iterative/dvc.org#593)

FYI @shcheklein's intention was to have dvc.org's "Use Cases" to be what I think you label "Features." I think to avoid confusion I'm going to stop using the term "use cases" forever because it is clearly too ambiguous to be fit for purpose.

this is not exactly true. I prefer the section Use Cases (and they are clearly not features in my head). We have features page on the website (that's actually about features) - that one is boring and can be replaced with a summary of use case. And name can be changed potentially. But it's a discussion about the page, not docs. In docs I would keep explicit Use Cases sections that serves a purpose of explaining high level problems tools can solve.

I agree about consistent path naming vs dvc.org

my 2cs - consistency is good (we do this gradually for the websites). Bad ideas from the previous project should not harm the new one. Redoing conventions just for the sake of subjective preferences - probably I would try to avoid that.

will be shifting to the proposed cml.dev layout

layout != URL/folder names though ... at least that's not the way I understood this :)

👍🏼 for longer paths: to my tastes, explicit is better than implicit.

a signal that topic is largely subjective? (I won't be sharing my preferences here :) ) - just saying that it's probably a signal that it's not that important?

So are these features or use cases? Also keep in mind it's not clear Use Cases are documentation, we've been talking about moving them directly to dvc.org/use-cases for some time so maybe you want to do that from the beginning in cml.dev?

But they will always (never say always :) ) stay as part fo the docs side bar to my mind. See some comments on this above ^^

[shcheklein]

Now some comments on the actual proposal :)

features - as I mentioned, probably not the best term to replace Use Cases. If we want to literally list features - it can be even part of the doc's index/welcome page?

get started structure - things to think about here:

• do we want to go with GL/GH, or go with some basic parts of the product?
• if we keep GH/GL - can we unify and have a switch? Otherwise it won't scale. We'll have to do BB, Jenkins, Azure soon? To me it sounds like it's better to start with one simple Quick Start with some toggles. Or do a few sections - Basic Setup, Fist Report, Train in the cloud ?

Do we need to have install?

[0x2b3bfa0]

if we keep GH/GL - can we unify and have a switch? Otherwise it won't scale. We'll have to do BB, Jenkins, Azure soon? To me it sounds like it's better to start with one simple Quick Start with some toggles. Or do a few sections - Basic Setup, First Report, Train in the cloud ?

CML is mostly an abstraction layer over many competing ways of doing the same things. I like the idea of letting users customize their getting started experience through toggle switches for the different stack components. Apart from some terminology nitpicks, credentials and workflow syntax, documentation should be pretty much the same for every user.

The major risk I see in a vendor-centric approach is that we're going to end duplicating considerable amounts of information. Keeping separate pages documenting how to achieve the same things with GitHub, GitLab or GitOther could end up causing maintenance issues once the supported vendor list starts to grow.

(Loosely related thread)

[jorgeorpinel]

Related to the proposal (meta):

• Features and use cases are quite different things 🙂
• On consistency I think we all agree. We decide what's best here and apply to both projects (non subjective things)
• From doc.cml.dev/ref/#publish it's unclear what "ref" means I think. I'd at least extend that to full "reference". Or "cmd-ref" which is more consistent with proposed DVC docs paths i.e. "cli/cmd-ref" or "api-ref" (that was my point ⚔️). Not a very strong opinion, it's probably subjective indeed.

On the proposal itself:

• re features can be even part of the doc's index: In dvc.org/doc we have a few overview of features actually: in the Get Started index and in the What is DVC guide
• I like the idea to rethink GS into features (also more consistent with the DVC GS) and make an issue to implement a platform switcher or some other solution along those lines (GH, GL, Jenkins, etc.).

---

Mostly unrelated here (feel free to ignore):

• Do you have a suggested list or a few ideas for the synonym list @casperdcl ? I can't really think of many (maybe repo & project)
• Not opposed to subdomains but may complicate the Ops (see Docs engine request #56 (comment)). I don't think it's necessarily bad for SEO though @shcheklein, depends on the purpose of the non-docs part of our product websites. Could even make it easier to analyze traffic in the future.
• I don't understand why use cases have to be in docs @shcheklein . It could easily be a top-level website section

[shcheklein]

From SEO perspective it's better for us to have a single website, subdomain creates the second one. Google is smart enough in some cases to merge ranks, merge SERP results, etc, but as I mentioned - I would not rely on that and it's not only about Google at the end.

Could even make it easier to analyze traffic in the future.

it's as simple to split traffic with /doc as with doc. to my mind. Or close.

I don't understand why use cases have to be in docs @shcheklein . It could easily be a top-level website section

Because it's another opportunity to show them in a bit different context. We are optimizing UX here, not DRYing stuff for the sake of DRYing it (to reasonable extent). Also each use case is a page long, we can probably take some highlights our of each and show on a separate page cml.dev/cases or even on the landing page (as we pretty much do already). But when you click learn more we can take users to the docs to read it.

[jorgeorpinel]

it's another opportunity to show them in a bit different context. We are optimizing UX here, not DRYing stuff

Ah so you're thinking about having them both as a top section AND in docs? I'm not opposed to that. It's what I suggested for Get Started pages too BTW (in iterative/dvc.org#144 (comment)).

Does their context have an impact if we expect them to be landing pages though? They tend to link to docs docs (a lot) anyway. But OK sure, it's just one nav entry.

we can probably take some highlights our of each and show on a separate page cml.dev/cases

I do like the idea of listing all the use case summaries in a single top level page.

[shcheklein]

Ah so you're thinking about having them both as a top section AND in docs?

I don't know to be honest, how exactly they can look like as a top section - separate page? multiple pages? etc - it's a bit early to decide to my mind. It's better to have some use cases in the first place :)