Reference docs: use canonical URL / command names #10471
Conversation
_config.yml
Outdated
| @@ -11,7 +11,6 @@ incremental: true | |||
| permalink: pretty | |||
| safe: false | |||
| lsi: false | |||
| url: https://docs.docker.com | |||
There was a problem hiding this comment.
We need to double-check if this has no side-effects. I couldn't find any, but perhaps may have missed some
|
@usha-mandya ptal; open to feedback / suggestions |
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
thaJeztah
force-pushed
the
canonical_reference_urls
branch
2 times, most recently
from
2950f0e to
5c6df12
Compare
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
thaJeztah
force-pushed
the
canonical_reference_urls
branch
from
5c6df12 to
7300a68
Compare
|
Deploy preview for docsdocker ready! Built with commit 7300a68 |
|
This is a definite improvement over trying to maintain copies of these pages without them getting out of sync. Few issues I'm seeing:
From a UX perspective, the ideal for me would be a single command in the title and an alias section at the top of the page (similar to how Wikipedia adds a redirect section at the top of articles). E.g.:
I dug around but didn't see where the actual redirects were happening in these changes. Entirely possible I'm blind and need to do more digging in the page generator code, but if that's back in a private repo, let me know so I don't lose any more hair :) |
|
Thanks for the pull request. We'd like to make our product docs better, but haven’t been able to review all the suggestions. If the updates are still relevant, review our contribution guidelines and rebase your pull request against the latest version of the docs, then mark it as fresh with a Prevent pull requests from auto-closing with a /lifecycle stale |
Opening as draft
In the current reference documentation, separate pages are included for commands that have aliases. For example, a page exists for both
docker run(https://docs.docker.com/engine/reference/commandline/run/), and fordocker container run(https://docs.docker.com/engine/reference/commandline/container_run/)This situation is confusing, because it's difficult for users to learn that both commands are equivalent, but also because only one page has an extended description (and examples).
This PR:
<object>_<verb>.yamlfiles<object> <verb>counterpartsdocker run) and long-hand (docker container run) commands in the title.To discuss:
For some commands, the "short-hand" may actually be the preferred / canonical command, so instead of redirecting to the
<object>_<verb>page, we could redirect the other way round (redirectdocker container runtodocker run).I decided not to go that direction, because (even though lengthier to type), the
docker container runcommand:docker container stop,docker container rm)Because of the above, it's easier for users to both "discover" related commands, and to understand what type of object the command relates to. The same is less easy to discover with the short-hand commands. For example, to learn that
docker rmirelates to images, whereasdocker rmrelates to containers.To do
Update
usagedescriptions where possible, for example, the "usage" section (and--helpoutput) ofdocker rundoes not mention the aliases;We could probably update those to mention both variations:
For other commands, there's even more variations (
docker ps,docker container ls,docker container list,docker container ps); we need to decide what to do with those.