Docker CLI documentation - 2 sets of pages per command is confusing and frustrating

[ghost]

File: engine/reference/commandline/container_run.md

This is a global issue for many of the documentation pages for the Docker commands.

There are 2 sets of Docker CLI command pages for many of the Docker commands.
For instance these 2 commands perform the same exact function:

docker run docker run
docker container run docker container run

I understand why we have 2 different syntaxes; in Docker Version 1.13 the commands were "revamped" and "improved".

However the 2 sets of documentation pages for the commands is confusing and frustrating.
I being a Docker employee get paid to be frustrated. 😉
Our users, community, customers and partners should not be frustrated.

Example:

If you happen to navigate to the new improved docker container run command documentation page you cannot see any details or examples for any of the command's options.

For instance show me the syntax and/or an example of coding the --label option.
Zero, nada.

And there is no link or mention to go to the other page -> docker run

If you are lucky enough to find the original/old docker run command documentation page, all is good as it has more details and examples on the docker run and docker container run command.

For instance the docker run command page has details on the --label option including examples. But this page does not reference the docker container run command page nor mentions it.

The "2 sets" of pages need to be merged together, linked together etc.

Now, there are many other Docker commands (documentation pages) that have this very same issue.

@bermudezmt

[ahh-docker]

Completely agree with you @gforghetti. I'm working on getting it straightened out, and I'm going to have you in the loop with what I'm working on since you're customer facing. Thanks for your help with this!

[seemethere]

cc @thaJeztah

[bermudezmt]

@mark-church I wanted to get your thoughts on this issue - as it is relevant to the CLI documentation work that we have to produce soon. We've been aware of the duplicate reference pages issue for some time now, and are hoping to get your input before we go further in reorganizing/refactoring the CLI pages in general.

[docker-robott]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, add a comment on this issue.
If not, this issue will be closed in 14 days.

Mark the issue as fresh with a /remove-lifecycle stale comment.
Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[thaJeztah]

related: #10471

[docker-robott]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[thaJeztah]

/lifecycle frozen