doc: shorter links to user-guide

[skshetry]

Hi, I need a few shortlinks for the following, which I need for dvc exp init.

1. https://dvc.org/doc/user-guide/project-structure/pipelines-files
2. https://dvc.org/doc/user-guide/experiment-management/running-experiments

I'd prefer something like https://dvc.org/doc/pipelines-files or even https://dvc.org/pipelines-files. Or, something else that is much shorter and still readable/understandable.

Here's how we display it right now in dvc exp init:

Looking at the dvc's code, we only seem to have short links for man.dvc.org which redirects to command-reference. We could also have something similar like https://guide.dvc.org/running-experiments (though it's 2 characters lengthier than https://dvc.org/doc/running-experiments).

[jorgeorpinel]

I'd prefer something like https://dvc.org/doc/pipelines-files or even https://dvc.org/pipelines-files. Or, something else that is much shorter

I think we should use something like learn.dvc.org for user guide links (similar to man.dvc.org for the cmd ref). It would probably need some more customization options so you don't have to use the entire path after /user-guide/ which can be pretty long... The configuration could be part of the doc engine though, stored as a new field in sidebar.json (cc @rogermparent)

[rogermparent]

Since learn.dvc.org doesn't exist currently, IIRC we'll have to add another CloudFlare site with a page rule pointing to the desired page and then add a redirects-list.json entry to do more complex redirects- I'm only under the assumption this works since there's entries for other subdomains already.

I'm always of the "simplest is best" school of thought which would entail just adding redirects-list.json entries for https://dvc.org/doc/pipelines-files => https://dvc.org/doc/user-guide/project-structure/pipelines-files and https://dvc.org/doc/running-experiments => https://dvc.org/doc/user-guide/experiment-management/running-experiments.

That said, if the consensus is that we want a subdomain, we should be able to figure it out.

[shcheklein]

Making the global URL namespace (dvc.org/something) or even docs namespace (dvc.org/doc/*) is not the best idea, I think - it will create conflicts in the future that won't be easy to debug, it won't be easy to maintain (list can become large eventually with a lot of entries).

I would recommend to come up with something like:

s.dvc.org/something
dvc.org/s/something

(s stands for short)

it can be a general mechanism of short links that we'll have a way to maintain separately and use for different things w/o affecting the website regular workflow

[jorgeorpinel]

Yes some sort of internal short perma-linking system would be nice (outside of the docs enfine). Even maybe on link.iterative.ai

[jorgeorpinel]

Unrelated: we used to have a general eng label. Does anyone know what happened to it cc @casperdcl @iesahin thanks

[shcheklein]

It should be dvc specific though since we'll include into the help message.

[casperdcl]

maybe eng's been renamed team/web? idk

[iesahin]

there wasn't a general eng label when I have modified. We had website, and it became team/web, and we have two separate eng labels actually.

In general, I didn't delete the labels if there are issues with them.

content => team/docs
website => team/web

[iesahin]

Instead of a domain, I'd recommend to have redirects:

dvc.org/doc/user-guide => dvc.org/ug/

dvc.org/ug/experiment-management => dvc.org/ug/exp/ 

We can also have two letter redirects /gs, /uc, /cr for other sections.

These probably won't cause much conflicts.

[casperdcl]

I'd say "user guide" needn't show up in the URL at all ever

(dvc.org/doc/user-guide/experiment-management => dvc.org/doc/experiment-management)

[shcheklein]

I'd say "user guide" needn't show up in the URL at all ever

I think I miss your point. What if we have get-started/experiment-management and user-guide/experiment-management

We can also have two letter redirects /gs, /uc, /cr for other sections.

I won's solve the experiment-management/running-experiments problem in the initial @skshetry 's concern.

---

I still think we need to create a simple custom url shortener which anyone could use to their benefit. I don't see a particular reason to keep it about docs specifically (leak very specific docs structure into it).

[iesahin]

We can also have two letter redirects /gs, /uc, /cr for other sections.

I won's solve the experiment-management/running-experiments problem in the initial @skshetry 's concern.

dvc.org/doc/user-guide/experiment-management/running-experiments > dvc.org/ug/exp/run

[rogermparent]

Seems like the way we're talking about this entails a more elaborate system that just throwing in some redirects-list entries, but considering such a system may take a while, would it be better for now to just use redirects-list entries with some convention that the new solution will follow?

[shcheklein]

would it be better for now to just use redirects-list entries with some convention that the new solution will follow?

sounds good to me!

dvc.org/ug/exp/run

we are still polluting the global URL space with the docs structure.

Let's use some common third-level URL s.dvc.org or some designated global namespace - dvc.org/s for this please.

After that it will up to the author to put a link they like there. It can be even s.dvc.org/ug/exp/run

[casperdcl]

I'd say "user guide" needn't show up in the URL at all ever

I think I miss your point. What if we have get-started/experiment-management and user-guide/experiment-management

I was replying to a tangential discussion (#2967 (comment)).

In terms of this mostly unrelated issue (#2967, i.e. bespoke one-off shortlink), DVC team should open a PR?

I still think we need to create a simple custom url shortener which anyone could use to their benefit. I don't see a particular reason to keep it about docs specifically (leak very specific docs structure into it)

Let's use some common third-level URL s.dvc.org or some designated global namespace - dvc.org/s for this please.

After that it will up to the author to put a link they like there. It can be even s.dvc.org/ug/exp/run

I'd say that's another separate tangential meta issue, but fully agree.

[iesahin]

we are still polluting the global URL space with the docs structure.

Ok. We can use dvc.org/s/ug/... for the time being, and move to s.dvc.org/ug/... when the new domain is ready to serve. Given the time and configuration constraints, this looks like the simplest approach.

[shcheklein]

s.dvc.org is done (it's fast to create domains like this).

[iesahin]

Is it a CNAME for the dvc.org domain? We'll use redirects as usual?

[shcheklein]

We'll use redirects as usual?

Yep

[jorgeorpinel]

which I need for dvc exp init.

https://dvc.org/doc/user-guide/project-structure/pipelines-files
https://dvc.org/doc/user-guide/experiment-management/running-experiments

Hi. So is this closed by #3001? I don't see those 2 specific redirects in there. Cc @skshetry @iesahin thanks

[iesahin]

https://dvc.org/doc/user-guide/experiment-management/running-experiments is now https://s.dvc.org/g/exp/run

https://dvc.org/doc/user-guide/project-structure/pipelines-files is https://s.dvc.org/g/project-structure/pipelines-files

If you need shorter versions to these, please let me know or just submit a PR with s.dvc.org domain. @skshetry