第364篇：技术案例沉淀：如何写好一篇技术案例文章

关键词：技术写作、案例沉淀、知识管理、文档规范、技术传播

---

一、引言

技术案例文章是网络工程师知识沉淀的核心载体。一个好的技术案例不仅能帮助自己回顾和加深理解，更能帮助团队避免重复踩坑、加速新人成长。从第346篇到第363篇，我们已经完成了大量实战案例的编写，本篇回过头来总结"如何写好一篇技术案例文章"的方法论。

为什么技术案例写作如此重要： 1. 个人层面：费曼学习法——能写清楚说明真正理解 2. 团队层面：避免重复故障，加速问题排查 3. 组织层面：知识资产的积累与传承 4. 行业层面：提升个人技术影响力

1.2 网络工程师的写作困境

在实际工作中，网络工程师常面临以下写作痛点：

痛点	表现	破解方法
"技术会做，写不出来"	有实战经验但无法结构化表达	使用标准模板，先搭骨架再填内容
"怕写错或被质疑"	完美主义导致迟迟不动笔	先写初稿，完成比完美重要
"写出来没人看"	不知道读者需要什么	明确读者画像，用场景引入
"不知道写什么"	觉得日常工作"没什么好写的"	从排障记录开始，积累素材库
"写了但质量不高"	缺乏写作框架和方法	掌握金字塔原理和MECE结构

真实场景：某运维团队有20多名工程师，每年处理超过500个故障，但只有不到30%的故障被整理为案例。原因正是上述痛点的综合体现。后来团队引入"故障当日内必须提交排障记录模板"的机制，3个月后案例沉淀率提升至85%。

二、需求分析与方案设计

2.1 技术案例文章的价值链

2.2 技术案例的标准结构

章节	内容要求	篇幅占比	写作要点
一、引言/案例背景	故障现象、影响范围、业务场景	10%	用事实说话，量化影响
二、需求分析与方案设计	根因分析、排查思路、解决方案	20%	逻辑清晰，图表辅助
三、技术细节与实施	协议原理、配置命令、操作步骤	30%	命令真实可验证
四、实战配置/案例分析	完整配置、效果验证、对比数据	25%	前后对比，数据说话
五、经验总结	表格化经验清单	10%	可复用、可执行
思考题	1-3个开放性思考	5%	引导深度思考

2.3 写作质量评估标准

评估维度	优秀	合格	待改进
真实性	有真实数据、有现网验证	基于真实场景	纯理论推导
完整性	有始有终、有前因后果	主要环节齐全	关键环节缺失
可读性	结构清晰、图表丰富	结构基本合理	结构混乱
可复用性	经验可直接套用	需参考理解	过于特殊
技术深度	有协议级分析	有现象级描述	仅表面描述

2.4 四种常见技术文档的写作模板

技术文档分为四大类型，每种类型有其特定的结构和写作要点：

故障案例模板：

章节	内容要点	篇幅占比	示例
故障现象	时间、级别、影响范围、具体表现	10%	"14:23，P1级，30万用户受影响"
排查过程	按时间线，操作→现象→结论	30%	每条记录需有结论
根因分析	为什么发生、触发条件	20%	说清"为什么"而非"是什么"
解决方案	修复步骤、关键配置命令	20%	命令真实可验证
预防措施	监控、规范、自动化	10%	可执行的检查项
复盘总结	经验表格	10%	STAR法则提炼

技术方案模板：

章节	内容要点	示例
背景需求(Why)	现有问题、业务需求	"现网设备老化，故障率↑40%"
方案概述(What)	一句话说明核心思路	"采用Spine-Leaf+VXLAN架构"
方案设计(How)	架构图、技术选型、关键配置	附Mermaid拓扑图
方案对比	备选方案的优劣势分析	决策矩阵表格
实施计划	阶段划分、时间节点	灰度迁移策略
风险评估	可能问题及应对措施	回退方案

技术博客模板：

章节	写作技巧
Hook(开头)	用场景/数据/反常识吸引读者
背景	为什么这个话题重要
原理	用通俗语言解释核心概念
实战	故事化叙述，附命令输出
总结	核心收获 + 改进空间

SOP操作手册模板：

章节	内容要点	示例
前置条件	设备信息、材料、风险评估	"CE6865, VRP V200R019"
操作步骤	步骤号→操作→预期结果→异常处理	每条必须可执行
后置检查	业务验证清单、监控确认	"BGP邻居数≥X"
异常处理	常见问题及解决路径	"如出现Y情况，执行Z"
回退方案	触发条件和操作步骤	"30分钟内可回退"

三、技术细节与实施过程

3.1 写作前的准备工作

信息收集清单：

收集项	来源	用途
故障现象	告警系统、用户投诉	案例背景描述
时间线	运维日志、变更系统	事件时间线
配置快照	设备show/display输出	技术细节
抓包数据	Wireshark/tcpdump	协议级分析
性能数据	Telemetry、SNMP	量化指标
变更历史	变更管理系统	排除/确认变更影响

写作前的思考框架：

1. 这篇文章要解决什么问题？（价值定位）
2. 目标读者是谁？（技术深度调整）
3. 核心知识点是什么？（重点突出）
4. 有哪些可复用的经验？（经验提炼）
5. 读者看完能做什么？（行动指导）

3.2 各章节写作技巧

3.2.1 引言/案例背景

好的引言：

"2024年3月15日下午14:23，某电商核心业务数据库访问延迟从平均5ms飙升至200ms+，影响在线交易约30万笔/小时。经排查，根因为OSPF区域间路由震荡导致次优路径。"

差的引言：

"有一天我们发现网络很慢，后来发现是OSPF的问题。"

对比分析：

要素	好的引言	差的引言
时间	精确到分钟	模糊描述
影响	量化数据	主观描述
根因	直接点出	模糊指向

3.2.2 需求分析与方案设计

设计图表的原则： 1. 拓扑用Mermaid flowchart（不用ASCII图） 2. 交互用Mermaid sequenceDiagram 3. 状态机用Mermaid stateDiagram 4. 对比用表格 5. 配置用代码块

案例：好的方案设计描述

方案设计采用"先旁路验证、再逐步迁移"的策略：

Phase 1（验证期，1周）：
- 在现网旁路搭建测试环境
- 验证SR-TE路径的收敛时间和流量分担

Phase 2（灰度期，2周）：
- 选择非核心业务（办公网）先行迁移
- 观察7×24小时运行状态

Phase 3（全面切换，1周）：
- 业务窗口期进行核心业务切换
- 保留旧配置72小时以便快速回滚

3.2.3 技术细节与实施

配置命令的写作规范：

# 好的写法：有注释、有上下文
<CE6865> system-view
[CE6865] bgp 65001
[CE6865-bgp] peer 10.1.1.2 as-number 65002      # 配置eBGP对等体
[CE6865-bgp] peer 10.1.1.2 connect-interface LoopBack0  # 使用LoopBack建立会话
[CE6865-bgp] peer 10.1.1.2 bfd min-rx 1000 echo-interval 333  # 启用BFD毫秒级检测
[CE6865-bgp] quit

# 差的写法：无注释、无上下文
bgp 65001
peer 10.1.1.2 as-number 65002
peer 10.1.1.2 connect-interface LoopBack0
peer 10.1.1.2 bfd min-rx 1000 echo-interval 333

3.3 数据驱动的写作

量化对比表（优化前后）：

指标	优化前	优化后	改善幅度
故障收敛时间	15s	50ms	99.7%
链路利用率	85%	42%	↓50%
丢包率	0.1%	0%	100%

关键原则： 1. 所有数据必须真实、可追溯 2. 对比数据需注明测试条件一致 3. 百分比改善需附上绝对值

3.4 经验总结的提炼方法

经验提炼的STAR法则：

要素	说明	示例
S (Situation)	在什么场景下	OSPF多区域部署
T (Task)	面临什么问题	路由震荡频繁
A (Action)	采取了什么措施	启用BFD+缩短Hello间隔
R (Result)	结果如何	收敛时间从15s降至50ms

经验表格的标准格式：

序号	经验类别	经验内容	适用场景
1	收敛优化	BFD+OSPF组合可将收敛从秒级降至毫秒级	高可靠场景

四、实战配置/案例分析

4.1 实战写作练习：从排错到文章

原始排错记录（不完整的）：

故障：用户报无法上网
排查：ping不通网关
发现：ARP表缺失
原因：VLANIF未up
解决：检查物理端口，发现光模块故障

改写为完整案例：

## 一、案例背景

2024年5月20日09:15，某园区网络中财务部用户（VLAN 200）集中报障无法访问互联网，
影响范围约50人，故障持续约40分钟。

## 二、排查思路

按照OSI七层模型自底向上排查：
1. 物理层：检查接入交换机端口状态
2. 数据链路层：检查VLAN和Trunk配置
3. 网络层：检查路由和ARP
...

## 三、根因定位

通过display vlanif 200发现接口状态为down，进一步检查关联物理端口G0/0/24
光模块收光功率-45dBm（阈值-28dBm），判定为光模块故障。
...

4.2 完整案例示范：BGP 路由黑洞故障案例

以下展示一篇按照标准模板撰写的故障案例全文，作为写作参考：

# BGP 路由黑洞导致跨域业务中断故障排查

**关键词**：BGP、路由黑洞、Next-Hop、eBGP、路由反射器

---

## 一、案例背景

2024年7月18日22:15，某运营商核心网监控告警：PE1与PE2之间跨域业务（VRF Customer-A）
完全中断，影响约1200台终端设备访问云端业务，预计每分钟损失收入约2万元。
故障持续约45分钟后恢复。

**业务拓扑**：

![diagram](/media/articles/mermaid/case-364-001.png)

## 二、排查过程

### 2.1 第一轮排查（22:15-22:20）

**操作1**：检查PE1与PE2间直连物理链路

```bash
<PE1> display interface GigabitEthernet 1/0/1
GigabitEthernet1/0/1 current state : Up
Line protocol current state : Up

结论：物理层、链路层正常，排除物理故障。

2.2 第二轮排查（22:20-22:30）

操作2：检查PE1上VRF Customer-A的路由表

<PE1> display ip routing-table vpn-instance Customer-A
Routing Table : Customer-A
Destinations : 42        Routes : 42

Destination/Mask    Proto  Pre  Cost  NextHop         Interface
10.200.0.0/24       BGP    255  0     10.1.1.2        GE1/0/1
10.200.0.1          IPSys  -    0     Direct          GE1/0/1

操作3：在PE1上ping VRF中的目标地址

<PE1> ping -a 10.1.1.1 -vpn-instance Customer-A 10.200.0.100
PING 10.200.0.100: 56 data bytes, press CTRL_C to break
Request timeout for icmp seq 1
Request timeout for icmp seq 2
Request timeout for icmp seq 3
--- 10.200.0.100 ping statistics ---
3 packet(s) transmitted, 0 packet(s) received, 100.00% packet loss

结论：路由存在但流量不通，疑似Next-Hop不可达导致的路由黑洞。

2.3 第三轮排查（22:30-22:40）

操作4：检查PE1的全局路由表，确认Next-Hop可达性

<PE1> display ip routing-table 10.1.1.2
Destination : 10.1.1.2
Routing Table : Public
Destination/Mask    Proto  Pre  Cost  NextHop         Interface
10.1.1.2/32         BGP    255  0     10.10.0.2       POS1/1/1

操作5：继续追踪到下一跳

<PE1> display ip routing-table 10.10.0.2
Destination : 10.10.0.2
Destination/Mask    Proto  Pre  Cost  NextHop         Interface
10.10.0.2/32        OSPF   10   20    10.10.0.1       POS1/1/1

结论：全局路由表中存在到10.1.1.2的路由，但从OSPF学习到10.10.0.2的路由Cost异常偏高（正常应为10），怀疑IGP路由有问题。

2.4 根因定位（22:40-22:55）

操作6：检查eBGP Next-Hop属性

<PE1> display bgp routing-table vpn-instance Customer-A 10.200.0.0 24
BGP local router ID is 10.1.1.1
Status codes: * - valid, > - best, d - damped,
              h - history, i - internal, s - suppressed, S - Stale
              e - external, b - backup, N - NRR

 * > Network: 10.200.0.0/24
      NextHop: 10.1.1.2
      MED: 0, LocPref: 100, PrefVal: 0
      Path: 65002 65003, valid external

关键发现：eBGP对等体RR-B通告路由时，Next-Hop为10.1.1.2（RR-B的LoopBack地址）， 但PE1的全局路由表中到达10.1.1.2需要经过IGP Transit AS 65003的路由， 而AS 65003中的OSPF路由因链路故障发生了震荡。

根因分析：

层级	现象	说明
L3 (IGP)	OSPF路由震荡	AS 65003内部链路闪断，10.1.1.2可达性不稳定
L3 (BGP)	Next-Hop不可达	eBGP默认不修改Next-Hop，PE1无法解析10.1.1.2
L3 (VRF)	路由黑洞	VRF路由存在但不可用（invalid状态），流量被丢弃

三、解决方案

3.1 临时恢复（22:55）

# 在RR-B上配置next-hop-local，强制修改eBGP下一跳为本端地址
[RR-B] bgp 65002
[RR-B-bgp] peer 10.1.1.1 next-hop-local

恢复后验证：

<PE1> ping -a 10.1.1.1 -vpn-instance Customer-A 10.200.0.100
PING 10.200.0.100: 56 data bytes, press CTRL_C to break
Reply from 10.200.0.100: bytes=56 Sequence=1 ttl=61 time=12 ms
Reply from 10.200.0.100: bytes=56 Sequence=2 ttl=61 time=11 ms
Reply from 10.200.0.100: bytes=56 Sequence=3 ttl=61 time=10 ms
--- 10.200.0.100 ping statistics ---
3 packet(s) transmitted, 3 packet(s) received, 0.00% packet loss

3.2 长期优化

措施	配置示例	目的
启用BFD for BGP	peer x.x.x.x bfd min-rx 1000	BGP会话毫秒级故障检测
配置Route-Policy修改Next-Hop	route-policy NH permit next-hop 127.0.0.1	统一Next-Hop策略
IGP BFD加速收敛	ospf 1 bfd enable	IGP路由秒级→毫秒级收敛
增加BGP Graceful Restart	graceful-restart	路由震荡期间保持转发

四、经验总结

序号	经验	适用场景
1	eBGP跨AS传输时Next-Hop必须可达，否则产生路由黑洞	跨域MPLS-VPN
2	VRF路由"存在但不通"时，优先检查Next-Hop在全局路由表的可达性	VPN故障排查
3	IGP震荡会影响BGP Next-Hop解析，需部署BFD加速检测	高可靠组网
4	路由黑洞的典型表现：路由表中有路由但ping不通	通用排错思路

### 4.3 写作工具链

| 工具 | 用途 | 推荐度 |
|------|------|--------|
| Typora | Markdown编辑器 | ⭐⭐⭐⭐⭐ |
| Obsidian | 笔记管理与知识图谱 | ⭐⭐⭐⭐⭐ |
| Mermaid Live | 在线流程图预览 | ⭐⭐⭐⭐ |
| Draw.io | 复杂架构图绘制 | ⭐⭐⭐⭐ |
| Wireshark | 抓包分析与截图 | ⭐⭐⭐⭐⭐ |
| Git | 版本管理 | ⭐⭐⭐⭐ |

### 4.3 知识库管理建议

![diagram](/media/articles/mermaid/case-364-002.png)

**知识库标签体系**：

| 标签维度 | 标签示例 |
|---------|---------|
| 协议域 | OSPF、BGP、MPLS、VXLAN、SRv6 |
| 场景 | 园区网、数据中心、运营商、无线 |
| 问题类型 | 连通性、性能、安全、排错、设计 |
| 厂商 | 华为、Cisco、Juniper、Arista |
| 难度 | 初级、中级、高级 |

### 4.4 完整技术案例Markdown模板

以下模板可直接复制使用，按需删减章节：

```markdown
# 第XXX篇：[故障/方案]的一句话标题

**关键词**：关键词1、关键词2、关键词3、关键词4、关键词5

---

## 一、案例背景

### 1.1 业务场景
- 客户行业/规模：[描述]
- 网络架构：[设备型号/数量/拓扑类型]
- 故障/需求触发点：[具体时间、现象、影响范围]

### 1.2 故障现象/需求描述
> 用1-2句话精准描述核心问题，包含时间、级别、影响范围（量化）。

| 维度 | 具体内容 |
|------|---------|
| 故障时间 | YYYY-MM-DD HH:MM |
| 影响范围 | X台设备 / X万用户 / X元损失 |
| 故障级别 | P1/P2/P3 |
| 持续时长 | X小时X分钟 |

## 二、需求分析与方案设计

### 2.1 问题分析
- 排查思路/设计目标
- 可能的根因假设列表（按可能性排序）

### 2.2 网络拓扑
> **此处用 Mermaid 绘制网络拓扑图（示例位置）**

### 2.3 解决方案概述
| 方案选项 | 优点 | 缺点 | 适用条件 | 最终选择 |
|---------|------|------|---------|---------|
| 方案A | ... | ... | ... | ✓ |
| 方案B | ... | ... | ... |   |

## 三、技术细节与实施过程

### 3.1 核心原理
> 涉及的协议机制或技术原理，不超过300字。

### 3.2 故障排查/实施步骤

#### 步骤1：[检查项]
```bash
# 命令（带注释）
<device> command
# 输出（只截关键行）

结论：[正常/异常，下一步指向]

步骤2：[检查项]

# ...

结论：...

3.3 根因定位/关键配置

层级	现象	说明
物理层	...	...
数据链路层	...	...
网络层	...	...

3.4 修复/实施方案

# 关键配置命令（带注释）

3.5 验证结果

# 修复后的验证命令和输出

四、实战配置/案例分析

4.1 完整配置模板

# 可直接复用的标准配置

4.2 效果对比

指标	优化前	优化后	改善
...	...	...	...

五、经验总结

序号	经验类别	经验内容	适用场景
1	...	...	...
2	...	...	...

思考

1. [开放性思考题1]
2. [开放性思考题2]
3. [开放性思考题3]

下篇预告：第XXX篇：[下一篇文章标题]

### 4.5 技术案例质量检查清单（20项）

在发布技术案例前，逐条对照以下清单进行自检：

| 序号 | 检查项 | 检查方法 | 通过标准 | 优先级 |
|------|--------|---------|---------|--------|
| 1 | 标题准确性 | 阅读标题 | 标题一句话概括核心问题 | 高 |
| 2 | 关键词完整性 | 检查关键词行 | 至少3-5个关键词，涵盖协议/场景/厂商 | 高 |
| 3 | 案例背景真实性 | 核对原始记录 | 有具体时间、影响范围、设备信息 | 高 |
| 4 | 数据量化 | 搜索"大约""很多""严重"等模糊词 | 所有影响数据已量化 | 高 |
| 5 | 拓扑图完整性 | 检查是否有拓扑图 | 有Mermaid拓扑图且与文字描述一致 | 高 |
| 6 | 排查步骤逻辑性 | 逐条阅读排查过程 | 步骤有先后逻辑，每步有结论 | 高 |
| 7 | 命令真实性 | 抽查2-3条命令 | 命令在目标设备上可执行 | 高 |
| 8 | 命令注释 | 检查代码块 | 每条关键命令有行内注释 | 高 |
| 9 | 输出截取合理性 | 检查命令输出 | 只截取关键行，不粘贴全量输出 | 高 |
| 10 | 根因分析深度 | 阅读根因段落 | 说明"为什么"而非仅"是什么" | 高 |
| 11 | 方案对比 | 检查是否有备选方案 | 至少列出2个方案并说明选择理由 | 中 |
| 12 | 经验表格格式 | 检查经验总结 | 使用标准4列表格格式 | 中 |
| 13 | 图表规范性 | 检查所有图表 | 不用ASCII图，用表格或Mermaid | 中 |
| 14 | 术语首次说明 | 搜索专业术语 | 首次出现的缩写在括号中说明 | 中 |
| 15 | 代码块语言标识 | 检查代码块 | 所有代码块有语言标识（bash/python等） | 中 |
| 16 | 思考题质量 | 阅读思考题 | 3个开放性思考题，非是非题 | 中 |
| 17 | 前后对比数据 | 检查优化效果 | 有优化前后的量化对比表 | 中 |
| 18 | 排版一致性 | 全局浏览 | 标题层级、缩进、间距一致 | 低 |
| 19 | 拼写和标点 | 通读全文 | 无错别字，中英文标点使用正确 | 低 |
| 20 | 交叉引用 | 检查预告和引用 | 下篇预告正确，引用其他篇时标注篇号 | 低 |

### 4.6 不同类型技术文章的写作要点对比

| 维度 | 故障案例 | 技术方案 | 原理科普 | 操作手册(SOP) | 经验总结 |
|------|---------|---------|---------|--------------|---------|
| 核心目标 | 记录排错过程，避免重复故障 | 提供可执行的方案 | 让读者理解"为什么" | 让任何人能复现操作 | 提炼可复用经验 |
| 结构重点 | 时间线+排查步骤 | 方案对比+实施计划 | 概念解释+类比 | 步骤+预期结果 | 表格化经验清单 |
| 数据要求 | 真实故障数据 | 容量/性能测算 | 原理示意图 | 版本号/参数值 | 量化效果指标 |
| 命令要求 | 每条有结论 | 完整配置模板 | 可选演示命令 | 精确到参数 | 关键命令即可 |
| 图表类型 | 拓扑图+时序图 | 架构图+对比表 | 原理图+类比图 | 步骤流程图 | 对比表 |
| 可读性要求 | 故事化叙述 | 结构化呈现 | 通俗化表达 | 精确无歧义 | 简洁有力 |
| 篇幅控制 | 3000-5000字 | 5000-8000字 | 2000-4000字 | 1000-3000字 | 1000-2000字 |
| 目标读者 | 运维工程师 | 方案设计者 | 初学者/培训 | 实施人员 | 所有级别 |

### 4.7 技术写作常见错误与改进建议

| 序号 | 错误类型 | 错误示例 | 改进后 | 原因分析 |
|------|---------|---------|--------|---------|
| 1 | 开头过度铺垫 | "随着5G技术的快速发展，网络拓扑变得越来越复杂..." | "本文分析某5G核心网BGP路由震荡故障" | 读者想知道结论，不想读背景 |
| 2 | 模糊量化 | "故障影响了很多用户，网络很慢" | "故障影响1200台终端，延迟从5ms升至200ms" | 模糊描述无法评估影响 |
| 3 | 缺少根因 | "我们重启了设备后恢复了" | "根因为内存泄漏导致BGP进程OOM，已提交补丁" | 不找根因就写了等于没写 |
| 4 | 命令堆砌 | 粘贴50行display输出无筛选 | 截取关键5-10行，每行加注释 | 大量输出让读者无法定位重点 |
| 5 | 术语裸奔 | "因为RT不对，所以VPN不通" | "因为RT（Route-Target，路由靶标）配置不匹配..." | 新手看不懂缩写 |
| 6 | 一步跳跃 | "然后配置了BFD就好了" | "配置BFD加速故障检测（min-tx 100ms），收敛从30s降至100ms" | 缺少实现细节 |
| 7 | 没有对比 | "优化后网络好多了" | "优化前丢包率0.5%，优化后0%，详见对比表" | 缺少数据对比无法评估效果 |
| 8 | 命令不可验证 | 编造不存在的命令参数 | 在目标设备上实际执行验证后再写入 | 编造命令会误导读者 |
| 9 | 结论先行 | 最后才说"根因是光模块故障" | 引言就写明"根因为光模块老化导致收光功率衰减" | 读者应先知道结论再读细节 |
| 10 | 经验不提炼 | 只有现象描述没有经验表格 | 使用标准4列表格：序号/类别/内容/场景 | 不提炼经验就无法复用 |
| 11 | 缺少拓扑 | 纯文字描述"设备A连接设备B再连设备C" | 附Mermaid拓扑图+文字描述 | 拓扑图一秒理解，文字需要反复读 |
| 12 | 忽略回滚 | 只写正向操作不写回退 | 每个关键步骤附带"如遇异常，执行XX回退" | 没有回滚方案的变更是冒险 |
| 13 | 主观表述 | "我觉得是OSPF的问题" | "OSPF邻居状态为Init，持续2分钟未变化" | 技术写作用事实，不用感觉 |
| 14 | 排版混乱 | 标题层级跳跃（一→1.1→3.2） | 严格按一→1.1→1.1.1层级递进 | 层级混乱导致结构不清 |
| 15 | 缺少时间线 | 排错过程没有时间标注 | 按时间线记录：22:15发现→22:30定位→23:00修复 | 没有时间线无法复现排错节奏 |

## 五、写作技巧与规范

### 5.1 用词规范

| ✅ 推荐 | ❌ 避免 | 原因 |
|---------|---------|------|
| 配置了BGP路由策略 | 进行了BGP路由策略的配置 | 删除"进行""做出"等冗余词 |
| 延迟为50ms | 延迟大概50ms左右 | 量化表达，不模糊 |
| 确认OSPF邻居Down | 我觉得OSPF邻居可能是Down的 | 肯定表达，不主观 |
| 排除了物理层故障 | 基本排除了物理层的问题 | 简洁有力 |

### 5.2 常见写作错误

| 错误类型 | 错误示例 | 正确写法 |
|---------|---------|---------|
| 开头铺垫过长 | "随着网络技术的快速发展..." | 直接切入主题 |
| 内容没有重点 | 一篇覆盖5个不相关话题 | 一篇只讲一个核心问题 |
| 没有"So What" | 描述完现象就结束 | 给出结论和建议 |
| 术语不解释 | 直接使用"RT"、"RD"等缩写 | 首次出现时简要说明 |
| 命令无注释 | 直接粘贴大段命令 | 每条命令标注目的 |
| 全量粘贴输出 | 粘贴几百行display输出 | 只截取关键行 |

### 5.3 图表使用原则

| 场景 | 推荐图表 | 避免 |
|------|---------|------|
| 网络拓扑 | Mermaid flowchart / draw.io | ASCII框线图 |
| 排查过程 | Mermaid sequenceDiagram | 纯文字叙述 |
| 状态变化 | Mermaid stateDiagram | 复杂表格 |
| 数据对比 | Markdown表格（含改善幅度列） | 截图照片 |
| 配置示例 | 带语言标识的代码块+注释 | 纯文本 |
| 协议交互 | Mermaid sequenceDiagram | 手绘拍照 |

**原则**：一图胜千言，但每图必须配有说明文字。图表不是装饰，而是帮助读者理解复杂逻辑的工具。

### 5.4 代码块写作规范

```bash
# ✅ 好的写法：有注释、有上下文、只截关键行
<CE6865> display bgp peer
BGP summary information
Total Number of Peers: 4
Peers            State   AS  MsgRcvd  MsgSent  Up/Down
10.1.1.2        Estab  65002  15234    15100   3d12h    # 关键peer正常

<CE6865> display bgp routing-table peer 10.1.1.2
# 查看从该Peer学习的路由详情

# ❌ 差的写法：无注释、全量粘贴
display bgp peer
BGP local router ID : 10.1.1.1
...（省略50行无关信息）

六、写作习惯养成

6.1 三阶段成长路径

阶段	时间	目标	产出	关键动作
第1阶段：写给自己	1-3月	养成记录习惯	排障日志	每日写100字工作记录
第2阶段：写给团队	3-6月	结构化表达	技术案例	每周整理1篇案例
第3阶段：写给行业	6-12月	建立品牌	技术博客	每月发布1篇文章

6.2 高效写作流程

6.3 写作素材积累方法

时机	动作	工具
故障发生时	实时记录操作和现象	手机备忘录
故障恢复后	整理为排障记录	模板文档
周末复盘	提炼经验，补充原理	知识库
每月汇总	形成完整技术案例	Markdown

关键：素材积累要在故障处理的"热度期"（24小时内），超过72小时，细节记忆会衰减80%。

七、经验总结

序号	经验类别	经验内容	适用场景
1	写作态度	先写后改，完成比完美更重要	所有写作
2	结构先行	先搭骨架再填内容，结构决定质量	技术文章
3	数据驱动	用真实数据说话，避免模糊描述	效果对比
4	图表辅助	一图胜千言，图表提升可读性	复杂概念
5	命令真实	配置命令必须真实可验证	实战案例
6	经验提炼	用STAR法则提炼可复用经验	经验总结
7	读者视角	站在读者角度审视可读性	质量评审
8	持续迭代	根据反馈持续优化文章内容	版本维护
9	知识关联	建立案例之间的交叉引用	知识管理
10	分享文化	好文章的价值在于被阅读和使用	团队文化

思考

1. 在快节奏的项目交付中，如何平衡"写完案例"和"完成项目"的时间投入？
2. 什么样的技术案例最值得沉淀？是解决复杂故障的案例还是日常常见问题的案例？
3. AI辅助写作（如大模型生成初稿）能否替代人工撰写技术案例？各自的优势和局限是什么？

下篇预告：第365篇：数通技术的未来：AI 与网络深度融合（全系列终篇）