Claude-skill-registry-data misc

技术写作的首要诀窍

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/misc" ~/.claude/skills/majiayu000-claude-skill-registry-data-misc && rm -rf "$T"

manifest: data/misc/SKILL.md

source content

技术写作的首要诀窍

阮一峰的网络日志

技术写作非常重要，产品的开发、推广、维护都需要它。

跟大家想的不一样，技术写作的好坏，跟语文水平关系不大，更多是一个技巧问题。

因为技术写作的评价标准，不是艺术性，而是表达是否清楚明白。它不需要华丽的词藻、巧妙的比喻、深刻的感悟，只需要把问题说清楚。

把问题说清楚的关键，在于你的思想是否清楚。

当你想清楚了一个问题，只要掌握几个基本诀窍，就能写出一篇很好的技术文章。

今天，我来说说，技术写作的首要诀窍是什么。很简单，就是一句话：文章采用单线结构。

所谓“单线结构”（也称“线性结构”），指的是一篇文章只说一件事，按照线性顺序进行叙述，由浅入深、循序渐进、平铺直叙、层层递进。

这就好比一个游览区，只有一条游览路线，从入口到出口，跟着箭头一路走，就能看到所有景观，非常明白清楚。

如果同时有好几条路线，游客就会糊涂，到底选哪一条？会不会错过景观？要是这些路线还互相交叉，那就更糟糕了，游客非串线不可。

（图片说明：上面的景区路线图，应该选择哪条路线吗？）

只要采用了单线结构，技术文章就不会太差。即使内容是难懂的，至少结构是清晰的，一环扣一环，读者能知道自己卡在哪一环上。只要克服了这个难点，就能继续往前走，不会有陷入迷宫、找不到方向、如坠五里雾中。

有一篇老外的文章[7]，使用图形表示文章结构，非常形象。

上图就是单线结构，按照箭头，一步步推进。

有的问题比较复杂，涉及多个因素，可能是星状结构。

也可能是”层次结构”。

这时，建议把这个问题拆分成多篇文章，每篇文章保持单线结构，坚持做到一篇文章只讲一点，而且争取把这一点讲透。

但是，单线结构说起来容易，做起来难。难就难在，人类的思想不是单线的，而是多线的，甚至是非线性。

你要把混乱而跳跃的思维，整理成单线结构，表达出来，让他人理解，谈何容易，通常都需要反复推敲和提炼。

举例来说，我们的思维可能是下图这样，好多点各自发散，连接在一起。

这种乱麻一团的思维并不可怕，可怕的是，你把文章也写成这样的结构，而不是耐心地梳理出一条线索。