reference: find a better way to present flag descriptions and example sections

未关闭
  • 哪里不对？
#16,470 4 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
文档
描述清晰度
需要澄清
活跃度
停滞
技术栈
docker
领域
documentation

调研方向

未指定文件或测试。先查看相关 issue 16469 和当前的 Docker 参考页面，然后比较各个项目如何组织 flag 描述和示例；当就一种一致的呈现方式达成共识并完成文档记录时，即视为完成。

由索引模型根据 Issue 内容生成。

描述

kind/enhancement lifecycle/frozen

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;

Screenshot 2023-01-09 at 12 28 59

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".

Screenshot 2023-01-09 at 12 29 29

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?

主要语言
Markdown
星标
4.7k
派生
8.5k
平均合并
2 天 8 小时
30 天内合并 PR
129

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

docker/docs 的其他 Issue

查看 docker/docs 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。