makerjackie MJ Book Writer
写技术橙皮书，不是把官方文档翻译成中文。
这份 skill 吸收了 makerjackie-writer 里最有效的部分，但把目标换成了技术书写作：要讲人话，要有作者判断，要知道读者卡在哪里，同时又不能牺牲事实密度。
写作目标
- 像一个长期在用这个产品的人写的
- 读者能迅速知道“这东西是什么、好在哪、坑在哪、什么时候别用”
- 不照抄文档，不写成公关稿，也不写成空洞评论
核心方法
1. 先有“作者判断”，再有“事实堆叠”
每一章开写前，先写出 3 句内部草稿，不必出现在正文里：
- 我对这章主题的核心判断是什么
- 读者最容易误解的地方是什么
- 哪件事最值得提前说清楚
没有这 3 句，正文很容易沦为文档改写。
2. 永远从使用顺序切入，不从产品定义切入
技术书最容易写坏的地方，是第一段就变成“X 是一个……”。更好的顺序通常是：
- 读者最可能先遇到的场景
- 为什么大家会走到这一步
- 这时 Cloudflare/某产品真正解决了什么
- 再补官方定义
3. 写“选择”，不要只写“能力”
每章至少回答下面四个问题中的三个：
- 为什么有人会选它
- 为什么有人会误用它
- 它替代了什么麻烦
- 它不适合什么场景
4. 让事实层和判断层交替出现
理想节奏不是：
- 一大段事实
- 一大段总结
而是：
- 先抛一个判断
- 用一个官方事实或产品行为支撑
- 立刻解释这对读者意味着什么
5. 每章都要有“去文档腔”动作
至少做到其中两个：
- 把抽象名词换成真实使用动作
- 把产品能力换成“它帮你少操心什么”
- 把限制条件换成“你会在哪一步撞墙”
- 把组件关系换成“你该先学哪个、后学哪个”
推荐章法
开头
从一个真实使用入口切，不要从大词切。
好开头像这样：
- 很多人第一次用 Cloudflare，其实只是想把站点接上去。
- 大多数人不是为了学边缘计算才打开 Workers，而是因为原来的后端太笨重了。
- 讨论中国网络时，最容易犯的错，是把三件完全不同的事混成一件。
坏开头像这样：
- X 是业界领先的……
- 随着技术发展……
- 在当今时代……
主体
一章建议按下面的顺序推进：
- 先说清读者为什么会关心这件事
- 再说产品/能力怎么工作
- 再说它解决了什么问题
- 最后说边界、误区和建议
结尾
结尾不要写成“综上所述”。更好的收法是：
- 点明这章最重要的取舍
- 告诉读者下一章为什么要继续看
- 或把一个常见误解轻轻纠正回来
语言要求
应该多用
- “很多人第一次……”
- “真正麻烦的地方在于……”
- “这也是为什么……”
- “更准确的说法是……”
- “别把它想成……，更像……”
- “如果你已经走到这一步……”
应该少用
- “赋能”
- “全面覆盖”
- “显著提升”
- “本质上”
- “换句话说”
- “意味着什么”
- “说白了”
- “首先、其次、最后”
反 AI 味检查
写完每章，至少过这 6 条：
- 第一段是不是像文档导语
- 有没有连续三句都在解释概念，没有真实场景
- 有没有“既……又……”这种平滑到发假的句式
- 有没有把限制写得过于轻描淡写
- 有没有只写优点，不写误用成本
- 有没有作者自己的判断
Cloudflare 专项提醒
1. 少写产品目录，多写产品关系
不要为了“全”把每个产品都写得一样重。读者真正需要的是：
- 应该先学谁
- 谁跟谁最常一起出现
- 哪些产品看着像一类，其实解决的不是同一个问题
2. 中国章节必须拆线
永远分成三条线：
- 默认全球网络体验
- 官方 China Network
- 社区优选节点 / 优选 IP
3. 避免假装全知
对于价格、限额、可用区域、产品支持范围这些容易变化的内容：
- 能不写数字就不写数字
- 必须写时只引用最新官方资料
- 正文里优先写决策逻辑，不要把章节写成 changelog
一章的完成标准
- 读完能复述这个产品/主题的核心作用
- 读完知道它适不适合自己
- 读完知道下一步该学什么
- 读完不会觉得这是官方文档换皮