SuperAPI AI 工具集

technical-blog-writing

写作与研究

查看项目

更新于 10-16 07:09

技能介绍

Technical Blog Writing 是一项面向开发者受众的技术博客写作技能,重点在于输出结构清晰、代码可靠、语气直白的技术文章。资料给出了五类文章形态及其结构:教程 / How-To(先展示成品、列前置条件、逐步实现、完整代码与后续扩展);深度解析 / Explainer(概念价值、简化心智模型、详细机制、真实示例、权衡与不适用场景、延伸阅读);事故复盘 / Postmortem(事件摘要、时间线、根因分析、修复措施、防复发方案、教训);基准对比 / Benchmark(对比对象、可复现方法、结果图表、数据分析、带保留意见的推荐、原始数据);架构 / 系统设计(待解决问题、约束与需求、备选方案、选定架构与图示、接受的权衡、结果与教训)。

写作规则方面,技能强调直白语气(如“使用连接池”而非“你或许可以考虑”),承认权衡,团队决策用“we”,使用具体数字(如 p99 从 800ms 降到 90ms),引用来源与基准,并提及替代方案。同时列出开发者反感的写法:空泛开场、“众所周知”“只需”“很容易”“显然”等措辞、技术内容中夹带营销语言、把重点埋在大量背景之后。

代码示例要求:每个代码块可运行、展示完整可用的示例、围栏代码块标注语言、代码后展示输出结果、使用真实变量名(如 calculateTotalRevenue 而非 foo)、包含错误处理、固定依赖版本(如“Works with React 18.2”而非“React”)。资料还给出指数退避加抖动的示例代码格式。

解释深度需按受众信号调整:入门类解释全部概念、进阶类跳过基础深挖细节、对比类假定读者熟悉双方、构建类可略过基础;并建议在开头明确声明假定受众水平。

推荐结构与篇幅:标题(含主关键词、说明成果)、主图或示意图、TL;DR(2-3 句总结与关键结论)、问题 / 为什么重要、方案 / 我们如何做(分步解释 + 代码 + 输出)、结果(具体数字)、权衡与局限、结语、延伸阅读(3-5 条链接)。字数参考:快速技巧 500-800,教程 1500-3000,深度解析 2000-4000,架构文章 2000-3500,基准对比 1500-2500。

配图与视觉部分给出场景与图表类型对应关系(请求流用序列图、系统架构用方框箭头图、决策逻辑用流程图、数据模型用 ER 图、性能对比用柱状/折线图、前后对比用并排图),并给出通过 CLI 应用生成架构图与基准图表的命令示例。分发部分列出开发者常读平台与发布方式:自有博客(完整文章、内容首要归属)、Dev.to 与 Hashnode(交叉发布并设 canonical URL 指回原站,Markdown 导入)、Hacker News(链接提交,项目用 Show HN、故事用 tell HN)、Reddit(链接或讨论,遵守版规)、Twitter/X(线程摘要 + 链接)、LinkedIn(改编版本 + 链接),并给出通过 CLI 发布 X 线程的命令示例。

常见错误清单包括:无 TL;DR、代码示例损坏、未固定版本、“只需做 X”式措辞、架构无图、营销语气、无权衡章节、正文前铺垫过长、依赖未固定、无延伸阅读,资料同时给出对应修正方式。相关技能安装命令包括 seo-content-brief、content-repurposing、og-image-design。使用方式上,需先安装并登录 CLI:npx skills add belt-sh/cli,随后 belt login,再通过 belt app run 调用检索、图像生成、图表生成、发帖等应用。该技能的能力依赖外部 CLI 与应用调用,具体可用性、费用与平台授权情况资料未提供。