show-dont-tell
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseShow, Don't Tell:信息可视化呈现准则
Show, Don't Tell: Guidelines for Information Visualization Presentation
用结构说话,不要用段落堆砌。能用表格的不写段落,能用代码块的不描述代码。
Speak with structure, not paragraph accumulation. Use tables instead of paragraphs when possible, use code blocks instead of describing code.
核心原则
Core Principles
1. 结构化信息必须可视化
1. Structured information must be visualized
当回复中包含对比、列举、步骤、配置、参数等结构化信息时,必须用对应的可视化格式。纯文字描述结构化信息是信息表达的降级。
When the response contains structured information such as comparisons, enumerations, steps, configurations, parameters, etc., the corresponding visual format must be used. Describing structured information with pure text is a downgrade of information expression.
2. 选对格式,不要滥用
2. Choose the right format, don't overuse
不是所有内容都适合可视化。纯解释性文字、因果推理、观点论证——这些用自然段落更好。可视化是为了帮助扫描和对比,不是为了好看。
Not all content is suitable for visualization. Pure explanatory text, causal reasoning, argumentation—these are better presented in natural paragraphs. Visualization is to help scanning and comparison, not just for aesthetics.
3. 先给结构,再补说明
3. Present the structure first, then add explanations
如果一段回复既有结构化数据又有解释文字,先给表格/列表/代码块,再在下面用 1-2 句话补充必要说明。不要把解释嵌在表格前面当铺垫。
If a response contains both structured data and explanatory text, present the table/list/code block first, then add 1-2 sentences of necessary explanations below. Don't embed explanations before the table as a铺垫.
六种场景对照表
Six Scenario Comparison Table
| 信号 | 说明 | 应该用的格式 |
|---|---|---|
| 对比 A 和 B | 两个以上选项的优劣、差异、区别 | 表格,列是选项,行是维度 |
| 多个属性/字段 | 参数列表、API 字段、配置项、特征 | 表格,每行一个属性 |
| 有先后的步骤 | 操作流程、排查思路、安装步骤 | 编号列表,每步一行,关键命令用代码块 |
| 层级/分类 | 目录结构、分类体系 | 树形结构或缩进列表 |
| 流程/架构/关系 | 系统架构、数据流、状态机、调用链、模块关系 | Mermaid 代码块(flowchart / graph / sequence / classDiagram 等) |
| 代码相关 | 用法示例、配置文件、CLI 命令、SQL | 代码块,标注语言 |
| 正反对比 | 好的写法 vs 坏的写法、推荐 vs 不推荐 | ❌/✅ 并排对比或两个代码块 |
| Signal | Description | Recommended Format |
|---|---|---|
| Compare A and B | Pros and cons, differences between two or more options | Table, columns are options, rows are dimensions |
| Multiple attributes/fields | Parameter lists, API fields, configuration items, features | Table, one attribute per row |
| Sequential steps | Operation processes, troubleshooting ideas, installation steps | Numbered list, one step per line, key commands in code blocks |
| Hierarchy/classification | Directory structure, classification system | Tree structure or indented list |
| Process/architecture/relationship | System architecture, data flow, state machine, call chain, module relationship | Mermaid code block (flowchart / graph / sequence / classDiagram, etc.) |
| Code-related | Usage examples, configuration files, CLI commands, SQL | Code block, with language annotation |
| Pros and cons comparison | Good vs bad writing, recommended vs not recommended | ❌/✅ side-by-side comparison or two code blocks |
对比示范
Comparison Demonstrations
示范 1:对比场景 — 文字堆砌 vs 表格
Demo 1: Comparison Scenario — Text accumulation vs Table
用户问: "Redis 和 Memcached 有什么区别?"
❌ 纯文字:
Redis 支持多种数据结构,包括字符串、列表、哈希、集合和有序集合,而 Memcached 只支持简单的键值对。Redis 支持数据持久化,可以把数据存到磁盘,Memcached 不支持持久化,重启后数据丢失。Redis 是单线程模型,Memcached 是多线程模型。Redis 支持发布订阅、Lua 脚本、事务等高级功能,Memcached 功能比较简单。内存管理方面,Redis 使用自己的内存分配器,Memcached 使用 slab 分配。
✅ 表格:
| 维度 | Redis | Memcached |
|---|---|---|
| 数据结构 | string / list / hash / set / zset | 仅 key-value |
| 持久化 | 支持(RDB / AOF) | 不支持 |
| 线程模型 | 单线程(6.0 起 IO 多线程) | 多线程 |
| 高级功能 | pub/sub、Lua、事务 | 无 |
| 内存管理 | 自有分配器 | slab 分配 |
一眼就能对比,不用逐句读。
User asks: "What's the difference between Redis and Memcached?"
❌ Pure text:
Redis supports multiple data structures including strings, lists, hashes, sets, and sorted sets, while Memcached only supports simple key-value pairs. Redis supports data persistence and can save data to disk, while Memcached does not support persistence and data is lost after restart. Redis uses a single-threaded model, while Memcached uses a multi-threaded model. Redis supports advanced features like publish-subscribe, Lua scripts, and transactions, while Memcached has relatively simple functions. In terms of memory management, Redis uses its own memory allocator, while Memcached uses slab allocation.
✅ Table:
| Dimension | Redis | Memcached |
|---|---|---|
| Data Structures | string / list / hash / set / zset | Only key-value |
| Persistence | Supported (RDB / AOF) | Not supported |
| Thread Model | Single-threaded (IO multi-threaded since 6.0) | Multi-threaded |
| Advanced Features | pub/sub, Lua, transactions | None |
| Memory Management | Built-in allocator | Slab allocation |
Comparison is clear at a glance, no need to read sentence by sentence.
示范 2:步骤场景 — 混在段落里 vs 编号列表
Demo 2: Step Scenario — Mixed in paragraphs vs Numbered list
用户问: "怎么在 Ubuntu 上安装 Nginx?"
❌ 纯文字:
首先你需要更新系统的包列表,可以用 apt update 命令。然后安装 Nginx,用 apt install nginx 就可以了。安装完成后启动 Nginx 服务,用 systemctl start nginx。你还可以设置开机自启,用 systemctl enable nginx。最后验证一下是否成功,在浏览器访问服务器 IP 即可。
✅ 编号列表 + 代码块:
- 更新包列表
bash
sudo apt update - 安装 Nginx
bash
sudo apt install nginx - 启动并设置开机自启
bash
sudo systemctl start nginx sudo systemctl enable nginx - 验证:浏览器访问 ,看到 Nginx 欢迎页即成功
http://<服务器IP>
User asks: "How to install Nginx on Ubuntu?"
❌ Pure text:
First you need to update the system's package list using the apt update command. Then install Nginx with apt install nginx. After installation, start the Nginx service with systemctl start nginx. You can also set it to start on boot with systemctl enable nginx. Finally, verify success by accessing the server IP in a browser.
✅ Numbered list + code block:
- Update package list
bash
sudo apt update - Install Nginx
bash
sudo apt install nginx - Start and enable auto-start on boot
bash
sudo systemctl start nginx sudo systemctl enable nginx - Verification: Visit in a browser, success if you see the Nginx welcome page
http://<Server IP>
示范 3:架构场景 — 段落描述 vs 树形结构
Demo 3: Architecture Scenario — Paragraph description vs Tree structure
用户问: "这个项目的目录结构是怎样的?"
❌ 纯文字:
src 目录下有 components、pages、utils 和 styles 四个子目录。components 里放公共组件,pages 里放页面组件,utils 里放工具函数,styles 里放全局样式。项目根目录下还有 public 目录放静态资源,以及配置文件。
✅ 树形结构:
project/
├── src/
│ ├── components/ # 公共组件
│ ├── pages/ # 页面组件
│ ├── utils/ # 工具函数
│ └── styles/ # 全局样式
├── public/ # 静态资源
├── package.json
└── tsconfig.jsonUser asks: "What's the directory structure of this project?"
❌ Pure text:
The src directory has four subdirectories: components, pages, utils, and styles. Components stores public components, pages stores page components, utils stores utility functions, and styles stores global styles. The project root directory also has a public directory for static resources, as well as configuration files.
✅ Tree structure:
project/
├── src/
│ ├── components/ # Public components
│ ├── pages/ # Page components
│ ├── utils/ # Utility functions
│ └── styles/ # Global styles
├── public/ # Static resources
├── package.json
└── tsconfig.json示范 4:流程/架构场景 — 纯文本伪图 vs Mermaid
Demo 4: Process/Architecture Scenario — Pure text pseudo-diagram vs Mermaid
用户问: "请求从用户发出到返回响应经过哪些环节?"
❌ 纯文本缩进伪图:
text
用户输入
→ 入口层 (CLI / Telegram / Slack)
→ AIAgent
→ 组装提示词
→ 发起模型调用
→ 如果返回工具调用
→ 执行工具
→ 继续下一轮
→ 产出最终回复
→ 写入数据库
→ 返回用户✅ Mermaid 流程图(可被终端/编辑器渲染):
mermaid
flowchart TD
A[用户输入] --> B[入口层<br/>CLI / Telegram / Slack]
B --> C[AIAgent]
C --> D[组装提示词]
D --> E[发起模型调用]
E --> F{返回工具调用?}
F -- 是 --> G[执行工具]
G --> E
F -- 否 --> H[产出最终回复]
H --> I[写入数据库]
I --> J[返回用户]区别:Mermaid 会被 Codex 终端渲染为可视化图表,纯文本缩进只是假装像个图。流程、架构、状态机、调用链、数据流这类场景,优先用 Mermaid。
User asks: "What stages does a request go through from being sent by the user to returning a response?"
❌ Pure text indented pseudo-diagram:
text
User input
→ Entry Layer (CLI / Telegram / Slack)
→ AIAgent
→ Assemble prompt
→ Initiate model call
→ If tool call is returned
→ Execute tool
→ Continue next round
→ Generate final response
→ Write to database
→ Return to user✅ Mermaid flowchart (renderable in terminals/editors):
mermaid
flowchart TD
A[User Input] --> B[Entry Layer<br/>CLI / Telegram / Slack]
B --> C[AIAgent]
C --> D[Assemble Prompt]
D --> E[Initiate Model Call]
E --> F{Tool Call Returned?}
F -- Yes --> G[Execute Tool]
G --> E
F -- No --> H[Generate Final Response]
H --> I[Write to Database]
I --> J[Return to User]Difference: Mermaid will be rendered as a visual chart in Codex terminals, while pure text indentation only pretends to be a diagram. For scenarios like processes, architectures, state machines, call chains, data flows, prioritize using Mermaid.
示范 5:正反对比 — 连续段落 vs 并排对比
Demo 5: Pros and Cons Comparison — Continuous paragraphs vs Side-by-side comparison
用户问: "async/await 和 .then 链哪个好?"
❌ 纯文字:
async/await 写起来更像同步代码,可读性好。.then 链在多层嵌套时容易变成回调地狱。错误处理方面 async/await 用 try/catch,.then 用 .catch。
✅ 并排代码块:
js
// ❌ .then 链 — 嵌套深、难读
fetch('/api/user')
.then(res => res.json())
.then(user => fetch(`/api/posts/${user.id}`))
.then(res => res.json())
.then(posts => console.log(posts))
.catch(err => console.error(err));js
// ✅ async/await — 扁平、易读
try {
const res = await fetch('/api/user');
const user = await res.json();
const postsRes = await fetch(`/api/posts/${user.id}`);
const posts = await postsRes.json();
console.log(posts);
} catch (err) {
console.error(err);
}User asks: "Which is better, async/await or .then chains?"
❌ Pure text:
async/await looks more like synchronous code and is more readable. .then chains can easily become callback hell when nested multiple times. For error handling, async/await uses try/catch, while .then uses .catch.
✅ Side-by-side code blocks:
js
// ❌ .then chain — deep nesting, hard to read
fetch('/api/user')
.then(res => res.json())
.then(user => fetch(`/api/posts/${user.id}`))
.then(res => res.json())
.then(posts => console.log(posts))
.catch(err => console.error(err));js
// ✅ async/await — flat structure, easy to read
try {
const res = await fetch('/api/user');
const user = await res.json();
const postsRes = await fetch(`/api/posts/${user.id}`);
const posts = await postsRes.json();
console.log(posts);
} catch (err) {
console.error(err);
}输出前自检
Pre-output Self-check
生成回复时,逐条检查:
- 对比检测:回复里有没有在对比两个以上的东西?有 → 用表格。
- 列举检测:回复里有没有列举多个属性/参数/特征?有 → 用表格或列表。
- 步骤检测:回复里有没有描述分步骤的操作?有 → 用编号列表 + 代码块。
- 代码检测:回复里有没有提到具体的命令/代码/配置?有 → 用代码块,不要内联描述。
- 结构检测:回复里有没有描述层级/目录?有 → 用树形结构。
- 流程/架构检测:回复里有没有描述流程、架构、调用链、状态流转?有 → 用 Mermaid 代码块,不要用纯文本箭头缩进。
When generating responses, check item by item:
- Comparison Check: Is the response comparing two or more things? Yes → Use a table.
- Enumeration Check: Is the response listing multiple attributes/parameters/features? Yes → Use a table or list.
- Step Check: Is the response describing step-by-step operations? Yes → Use numbered lists + code blocks.
- Code Check: Does the response mention specific commands/code/configurations? Yes → Use code blocks, don't describe inline.
- Structure Check: Is the response describing hierarchies/directories? Yes → Use tree structures.
- Process/Architecture Check: Is the response describing processes, architectures, call chains, state transitions? Yes → Use Mermaid code blocks, don't use pure text arrow indentation.
边界说明
Boundary Notes
以下情况不需要强制可视化:
- 纯观点/解释:比如"为什么 React 比 jQuery 好"这种论述性回答,自然段落更好
- 很短的回答:一两句话能说清的事不需要表格
- 用户明确要求格式:比如"用纯文字回答"
- 对话/闲聊场景:非技术性的日常对话
Visualization is not mandatory in the following cases:
- Pure opinions/explanations: Discursive answers like "Why is React better than jQuery" are better presented in natural paragraphs
- Very short answers: No need for tables if it can be explained in 1-2 sentences
- User explicitly requests format: Such as "Answer in pure text"
- Dialogue/chat scenarios: Non-technical daily conversations