Do we need docs/content/en/docs?

[kentakozuka]

docs/ is supposed to be the same with docs of the latest version(e.g. docs-v0.44.x/).

Also, When we jump "Documentation" from the top page with a specific version being selected, we are navigated to docs/. This should be docs of the selected version.

[khanhtc1202]

This is a legacy problem. Previously, we only have one single docs which is /docs/, and after that, when we started versioning the docs, I thought links to /docs/ be referred out where (on other sites blog, for instance) should be kept alive. That's why we decided that we have to keep /docs and make it points to the latest version docs.

To ensure users who read about pipecd from other blogs do not get 404 not found error, we have to:

• configure to redirect all /docs/ to the "right" URL which we not sure what is what
• keep /docs/ and make it as same as the latest <- currently do this, since it's the simplest

WDYT? 🤔

[khanhtc1202]

When we jump "Documentation" from the top page with a specific version being selected, we are navigated to docs/. This should be docs of the selected version.

I think it works as expected, isn't it? 🤔

Kapture.2023-06-28.at.22.02.22.mp4

[kentakozuka]

I meant this;

Screen.Recording.2023-06-29.at.07.58.56.mov

But if /docs is the same as the latest version, it could be the expected behavior...

[kentakozuka]

I did not know the history of docs. That's good to know. Thanks!

So how about this?

• remove /docs/.
• configure to redirect all /docs/ to the latest URL (e.g. /docs-v0.44.0x on 2023-06-29)

because /docs/ and the latest versioned docs contain the same content.

[khanhtc1202]

Do you mean after that (on version v0.45.x release and so on), we don't do redirection any more, any require versioning docs url from now on 👀

[kentakozuka]

I meant we would do redirect /docs/ to the latest version.
/docs will be removed because all accesses to /docs/ will be redirected to the latest docs.

[kentakozuka]

@khanhtc1202
How about this simple way to do?
#4458

• Remove /docs-dev
• Treat /docs/ as master(I guess we already do that in our mind)

I looked at KubeFlow and they seem to do in this way.

[khanhtc1202]

Sorry but I don't think that way. First, the master means to dev version of the docs. Since it is docs for the not yet released version, I prefer to use the word dev over latest or master to mention that it's dev (not released) directly.

And besides, I don't think treating the /docs as master/dev/latest is a good idea. It should be treated as stable/latest-released docs, since it clearly means it's the documentation (users may don't aware of docs has other versions so /docs can be used as the only one)

This is the versioning of argocd (latest: dev / stable: latest released / versioning: ...)

[kentakozuka]

I just started to think the current directory structure and writing flow is good enough.

• We already have make gen/stable-docs.
• Removing /docs/ and setting up the redirect to the latest version is not that easy.

So I'm thinking to close this issue until someone has the same thought.
@khanhtc1202 wdyt?

[khanhtc1202]

For sure, let's make a discussion for this later if we have a better idea around the docs 👍