写面向开发者的技术博客时，如何按文章类型组织内容…

适用于撰写工程博客、开发教程、技术深度解析、事故复盘、基准对比和架构设计类文章，帮助开发者写出可信、可复现、易传播的技术内容。

适用场景

解决思路

1. 按文章类型选择结构：教程/How-To 用「要构建什么（含截图/演示）→ 前置条件 → 分步骤实现 → 完整代码（GitHub 链接）→ 后续扩展」；深度解析用「概念是什么及为何重要 → 简化心智模型 → 详细机制 → 真实案例 → 取舍与不适用场景 → 延伸阅读」；事故复盘用「摘要（发生了什么、影响、时长）→ 时间线 → 根因分析 → 修复措施 → 防复发计划 → 经验教训」；基准对比用「对比什么及原因 → 可复现的方法论 → 图表/表格结果 → 数据分析 → 带前提的建议 → 原始数据/复现说明」；架构设计用「要解决的问题 → 约束与需求 → 考虑过的方案 → 选定架构（含图）→ 接受的取舍 → 结果与教训」。
2. 教程类文章先展示最终结果，让读者判断是否值得继续；显式列出前置条件，避免浪费错误受众的时间；每个代码块都应可运行，以复制-粘贴-运行作为检验标准；解释「为什么」而不只是「怎么做」；包含错误处理；链接到完整代码仓库。
3. 写作语气要直接（如「Use connection pooling」而非「You might want to consider...」）；承认取舍（如「This adds complexity」）；团队决策用「we」；用具体数字（如「reduced p99 from 800ms to 90ms」）而非「significantly improved」；引用来源和基准；承认替代方案。
4. 避免开发者反感表达：不用「In today's fast-paced world of technology...」等填充语；不用「As we all know...」「Simply do X」「It's easy to...」「Obviously...」；技术内容中不用营销语言；不要把核心观点埋在 3 段背景之后。
5. 代码示例规则：每个代码块必须可运行；展示完整可工作的示例；围栏代码块标注语言标识符；代码后展示输出/结果；使用真实变量名（如 calculateTotalRevenue 而非 foo）；示例中包含错误处理；固定依赖版本（如「Works with React 18.2」而非「React」）。
6. 根据受众信号调整解释深度：「Getting started with X」解释一切、假设无前置知识；「Advanced X patterns」跳过基础、深入细节；「X vs Y」假设熟悉两者、聚焦差异；「How we built X」面向技术受众、可跳过基础。在开头显式声明假设的受众水平。
7. 采用理想结构：标题（含主关键词、说明成果）→ Hero 图或架构图 → TL;DR（2-3 句总结含关键结论）→ 问题/为何重要（具体而非泛泛）→ 解决方案/如何实现（核心内容：代码、架构、解释，分步骤含解释+代码+输出）→ 结果（具体数字、基准、成果）→ 取舍与局限（诚实说明缺点以建立信任）→ 结论（关键结论+下一步）→ 延伸阅读（3-5 个相关链接）。
8. 按类型控制字数：快速技巧 500-800 字；教程 1,500-3,000 字；深度解析 2,000-4,000 字；架构文章 2,000-3,500 字；基准对比 1,500-2,500 字。
9. 按场景选择图表：请求流用序列图；系统架构用方框箭头图；决策逻辑用流程图；数据模型用 ER 图；性能对比用柱状/折线图；前后对比用并排图。
10. 分发渠道：自有博客发全文（拥有内容主权）；Dev.to 和 Hashnode 交叉发布并设置 canonical URL 指回原文；Hacker News 提交链接（项目用 Show HN，故事用 tell HN）；Reddit（r/programming、r/webdev 等）发链接或讨论并遵守版规；Twitter/X 发线程摘要+链接；LinkedIn 发改编版本+链接。
11. 避免常见错误：没有 TL;DR（忙碌开发者会在看到重点前离开）→ 顶部放 2-3 句总结；代码示例损坏（摧毁可信度）→ 发布前测试每个代码块；未固定版本（6 个月后代码失效）→ 注明「Works with Node 20, React 18.2」；使用「Simply do X」（居高临下）→ 删除「simply」「just」「easily」；架构无图（大段文字描述系统）→ 一张图胜过 500 字描述；营销语气（开发者立即脱离）→ 直接、技术、诚实；无取舍章节（读起来像软文）→ 始终讨论缺点；开头冗长（读者跳出）→ 2-3 段内进入正题；依赖未固定（教程对未来读者失效）→ 固定版本并注明写作日期；无「Further Reading」（死胡同）→ 3-5 个链接深化理解。

适用边界 · 注意事项

• 需要依赖 inference.sh CLI（belt）及其应用（exa/search、infsh/html-to-image、infsh/python-executor、x/post-create）生成配图、图表和分发时，必须先安装并登录该付费/特定工具，纯写作场景不适用。
• 文章类型不属于工程博客、开发教程、技术深度解析、事故复盘、基准对比或架构设计时（如纯营销文案、非技术内容），本经验不适用。