You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Our reference docs currently use "descriptive" titles for flag descriptions. The idea behind that was to make these sections more discoverable, so that users that search for a specific "task" / "feature" would discover the flag they need to use for that.
For example;
Set the pull policy (--pull)
Using "Set the pull policy" allows the user to find the --pull flag, either from the right-hand TOC, or using search (within the docs, or through Google), and we also link to that section from the "options" table at the top of the page;
So, the current approach allows for two separate navigation entries into the content. However this approach also makes the right-hand navigation a bit unwieldy; the titles are long, and trying to find the right section for a specific flag from the right-hand TOC (not the table) is "messy".
We can probably improve some of that, but we need to brainstorm a bit on the right approach, and make sure that all projects that have pages in the reference section use the same approach.
A. Keep as-is, but add additional entries to the right-hand TOC
This could be a short-term solution; we keep the current headings, but repeat the links from the "options" table in the right-hand TOC. This means that (some) sections will appear twice in the TOC;
once using --flagname as title (e.g. --pull)
once using the heading title (Set the pull policy (--pull))
This approach
👍 makes the --flagnames easier to discover in the right-hand navigation
👍 example titles continue to be listed in the navigation to help discoverability
👎 possibly confusing (two links to the same section)
B. Use --flagname for the headings, and put the examples as separate headings inside that
This approach would "split" the flagname and examples. Both are linkable;
--workdir, -w
Set the working directory inside the container.
Set a custom working directory for a container
Description of this example, mention WORKDIR etc etc
$ docker container run --workdir=/foo .....
👍 makes the --flagnames easier to discover in the right-hand navigation
👎 / ❓ if we show both the --flagname and the "Set a custom working directory for a container" in the TOC, the TOC may still be cluttered
C. Separate examples and flag descriptions
Similar to A., but actually make the flag description and examples related to the flag separate sections (not nested).
👍 makes the --flagnames easier to discover in the right-hand navigation
👍 example titles continue to be listed in the navigation to help discoverability
👎 navigating to the flag description only provides a (basic) description for the flag; sometimes an example is more useful to understand "why to use this flag"
☝️ we can still link from the flag description section to the corresponding example(s), but this requires additional maintenance, and may make the flag description section a bit "cluttered" (short description, followed by potentially multiple links to the examples).
D. Other options?
Perhaps there's other options?
The text was updated successfully, but these errors were encountered:
I'm leaning towards option C for the following reasons:
This approach seems to be the most common among other tools. Doesn't mean it's better, but does mean that we wouldn't be deviating from what users might expect.
A clear and concise description of a resource (flag in this case) is the main purpose that reference documentation should fulfill.
Separating the flag descriptions to their own section makes it easier to navigate the CLI reference documentation based on flags.
Separating the examples from the flags helps when we show examples involving multiple flags.
Our reference docs currently use "descriptive" titles for flag descriptions. The idea behind that was to make these sections more discoverable, so that users that search for a specific "task" / "feature" would discover the flag they need to use for that.
For example;
Using "Set the pull policy" allows the user to find the
--pull
flag, either from the right-hand TOC, or using search (within the docs, or through Google), and we also link to that section from the "options" table at the top of the page;So, the current approach allows for two separate navigation entries into the content. However this approach also makes the right-hand navigation a bit unwieldy; the titles are long, and trying to find the right section for a specific flag from the right-hand TOC (not the table) is "messy".
We can probably improve some of that, but we need to brainstorm a bit on the right approach, and make sure that all projects that have pages in the reference section use the same approach.
A. Keep as-is, but add additional entries to the right-hand TOC
This could be a short-term solution; we keep the current headings, but repeat the links from the "options" table in the right-hand TOC. This means that (some) sections will appear twice in the TOC;
--flagname
as title (e.g.--pull
)Set the pull policy (--pull)
)This approach
--flagnames
easier to discover in the right-hand navigationB. Use
--flagname
for the headings, and put the examples as separate headings inside thatThis approach would "split" the flagname and examples. Both are linkable;
--flagnames
easier to discover in the right-hand navigation--flagname
and the "Set a custom working directory for a container" in the TOC, the TOC may still be clutteredC. Separate examples and flag descriptions
Similar to
A.
, but actually make the flag description and examples related to the flag separate sections (not nested).--flagnames
easier to discover in the right-hand navigationD. Other options?
Perhaps there's other options?
The text was updated successfully, but these errors were encountered: