technical-blog-writing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTechnical Blog Writing
技术博客写作指南
Write developer-focused technical blog posts via inference.sh CLI.
通过inference.sh CLI撰写面向开发者的技术博客文章。
Quick Start
快速开始
bash
curl -fsSL https://cli.inference.sh | sh && infsh loginbash
curl -fsSL https://cli.inference.sh | sh && infsh loginResearch topic depth
调研主题深度
infsh app run exa/search --input '{
"query": "building REST API Node.js best practices 2024 tutorial"
}'
infsh app run exa/search --input '{
"query": "building REST API Node.js best practices 2024 tutorial"
}'
Generate header image
生成标题图片
infsh app run infsh/html-to-image --input '{
"html": "<div style="width:1200px;height:630px;background:linear-gradient(135deg,#0f172a,#1e293b);display:flex;align-items:center;padding:60px;font-family:ui-monospace,monospace;color:white"><div><p style="font-size:18px;color:#38bdf8;margin:0">// engineering blog</p><h1 style="font-size:48px;margin:16px 0;font-weight:800;font-family:system-ui;line-height:1.2">How We Reduced API Latency by 90% with Edge Caching</h1><p style="font-size:20px;opacity:0.6;font-family:system-ui">A deep dive into our CDN architecture</p></div></div>"
}'
undefinedinfsh app run infsh/html-to-image --input '{
"html": "<div style="width:1200px;height:630px;background:linear-gradient(135deg,#0f172a,#1e293b);display:flex;align-items:center;padding:60px;font-family:ui-monospace,monospace;color:white"><div><p style="font-size:18px;color:#38bdf8;margin:0">// engineering blog</p><h1 style="font-size:48px;margin:16px 0;font-weight:800;font-family:system-ui;line-height:1.2">How We Reduced API Latency by 90% with Edge Caching</h1><p style="font-size:20px;opacity:0.6;font-family:system-ui">A deep dive into our CDN architecture</p></div></div>"
}'
undefinedPost Types
博客类型
1. Tutorial / How-To
1. 教程/操作指南
Step-by-step instruction. The reader should be able to follow along and build something.
Structure:
1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (GitHub link)
7. Next steps / extensions| Rule | Why |
|---|---|
| Show the end result first | Reader knows if it's worth continuing |
| List prerequisites explicitly | Don't waste time of wrong audience |
| Every code block should be runnable | Copy-paste-run is the test |
| Explain the "why" not just the "how" | Tutorials that explain reasoning get shared |
| Include error handling | Real code has errors |
| Link to complete code repo | Reference after tutorial |
分步式操作说明，读者可跟随步骤完成搭建。
结构：
1. 我们要搭建的内容（附截图/演示）
2. 前置要求
3. 步骤1：环境搭建
4. 步骤2：核心实现
5. 步骤3：...
6. 完整代码（GitHub链接）
7. 后续步骤/扩展方向| 规则 | 原因 |
|---|---|
| 先展示最终效果 | 让读者明确是否值得继续阅读 |
| 明确列出前置要求 | 避免浪费非目标受众的时间 |
| 每个代码块都可直接运行 | 复制-粘贴-运行是检验标准 |
| 不仅讲解“怎么做”，还要说明“为什么” | 包含推理过程的教程更易被分享 |
| 加入错误处理 | 真实代码会遇到错误 |
| 链接到完整代码仓库 | 方便读者在教程结束后参考 |
2. Deep Dive / Explainer
2. 深度解析/原理讲解
Explains a concept, technology, or architecture decision in depth.
Structure:
1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading深入讲解某个概念、技术或架构决策。
结构：
1. 什么是[概念]，为什么你需要关注它？
2. 工作原理（简化心智模型）
3. 工作原理（详细机制）
4. 实际案例
5. 取舍场景及不适用情况
6. 延伸阅读3. Postmortem / Incident Report
3. 事后复盘/事故报告
Describes what went wrong, why, and what was fixed.
Structure:
1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned描述问题发生的过程、原因及修复措施。
结构：
1. 摘要（发生了什么、影响范围、持续时间）
2. 事件时间线
3. 根本原因分析
4. 实施的修复方案
5. 预防复发的措施
6. 经验教训4. Benchmark / Comparison
4. 基准测试/对比分析
Data-driven comparison of tools, approaches, or architectures.
Structure:
1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions基于数据对比工具、方法或架构。
结构：
1. 我们对比的内容及原因
2. 测试方法（确保结果可复现）
3. 结果（含图表/表格）
4. 分析（数据背后的意义）
5. 推荐方案（附注意事项）
6. 原始数据/复现说明5. Architecture / System Design
5. 架构/系统设计
Explains how a system is built and why decisions were made.
Structure:
1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons讲解系统的构建方式及决策原因。
结构：
1. 我们需要解决的问题
2. 约束条件与需求
3. 考虑过的方案
4. 选定的架构（附示意图）
5. 我们接受的取舍
6. 结果与经验Writing Rules for Developers
面向开发者的写作规则
Voice and Tone
语气与语调
| Do | Don't |
|---|---|
| Be direct: "Use connection pooling" | "You might want to consider using..." |
| Admit trade-offs: "This adds complexity" | Pretend your solution is perfect |
| Use "we" for team decisions | "I single-handedly architected..." |
| Specific numbers: "reduced p99 from 800ms to 90ms" | "significantly improved performance" |
| Cite sources and benchmarks | Make unsourced claims |
| Acknowledge alternatives | Pretend yours is the only way |
| 建议做法 | 避免做法 |
|---|---|
| 直接表述：“使用连接池” | “你或许可以考虑使用...” |
| 承认取舍：“这会增加复杂度” | 假装你的方案完美无缺 |
| 团队决策用“我们” | “我独自设计了整个架构...” |
| 使用具体数字：“将p99延迟从800ms降低至90ms” | “显著提升了性能” |
| 引用来源与基准测试 | 提出无依据的主张 |
| 认可替代方案 | 假装你的方案是唯一选择 |
What Developers Hate
开发者反感的内容
❌ "In today's fast-paced world of technology..." (filler)
❌ "As we all know..." (if we all know, why are you writing it?)
❌ "Simply do X" (nothing is simple if you're reading a tutorial)
❌ "It's easy to..." (dismissive of reader's experience)
❌ "Obviously..." (if it's obvious, don't write it)
❌ Marketing language in technical content
❌ Burying the lede under 3 paragraphs of context❌ “在当今快节奏的技术世界中...”（冗余套话）
❌ “众所周知...”（如果真的众所周知，何必写出来？）
❌ “只需执行X操作”（如果读者需要看教程，就没有“只需”的事）
❌ “轻松就能...”（轻视读者的经验）
❌ “显然...”（如果真的显然，就无需写出）
❌ 技术内容中使用营销话术
❌ 用三段铺垫才进入正题Code Examples
代码示例规范
| Rule | Why |
|---|---|
| Every code block must be runnable | Broken examples destroy trust |
| Show complete, working examples | Snippets without context are useless |
| Include language identifier in fenced blocks | Syntax highlighting |
| Show output/result after code | Reader verifies understanding |
| Use realistic variable names | |
| Include error handling in examples | Real code handles errors |
| Pin dependency versions | "Works with React 18.2" not "React" |
Good code block format:
```python| 规则 | 原因 |
|---|---|
| 每个代码块必须可直接运行 | 错误的示例会失去读者信任 |
| 展示完整可运行的示例 | 无上下文的代码片段毫无用处 |
| 在代码块中指定语言标识 | 实现语法高亮 |
| 代码后展示输出/结果 | 帮助读者验证理解 |
| 使用真实的变量名 | |
| 示例中包含错误处理 | 真实代码需要处理错误 |
| 固定依赖版本 | 写明“适用于React 18.2”而非“React” |
优秀代码块格式：
```pythonWhat this code does (one line)
这段代码的作用（一行说明）
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
"""Exponential backoff with jitter."""
delay = base_delay * (2 ** attempt)
jitter = random.uniform(0, delay * 0.1)
return delay + jitter
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
"""带抖动的指数退避算法。"""
delay = base_delay * (2 ** attempt)
jitter = random.uniform(0, delay * 0.1)
return delay + jitter
Usage
使用示例
delay = calculate_retry_delay(attempt=3) # ~8.0-8.8 seconds
undefineddelay = calculate_retry_delay(attempt=3) # 约8.0-8.8秒
undefinedExplanation Depth
讲解深度适配
| Audience Signal | Depth |
|---|---|
| "Getting started with X" | Explain everything, assume no prior knowledge |
| "Advanced X patterns" | Skip basics, go deep on nuances |
| "X vs Y" | Assume familiarity with both, focus on differences |
| "How we built X" | Technical audience, can skip fundamentals |
State your assumed audience level explicitly at the start:
"This post assumes familiarity with Docker and basic Kubernetes concepts.
If you're new to containers, start with [our intro post]."| 受众信号 | 讲解深度 |
|---|---|
| “X入门指南” | 讲解所有细节，假设读者无前置知识 |
| “X高级模式” | 跳过基础内容，深入讲解细节差异 |
| “X与Y对比” | 假设读者熟悉两者，重点讲解差异 |
| “我们如何构建X” | 面向技术受众，可跳过基础知识 |
在文章开头明确说明目标受众的知识水平：
“本文假设读者已熟悉Docker和基础Kubernetes概念。
如果你是容器技术新手，请先阅读[我们的入门文章]。”Blog Post Structure
博客文章结构
The Ideal Structure
理想结构
markdown
undefinedmarkdown
undefinedTitle (contains primary keyword, states outcome)
标题（包含核心关键词，明确成果）
[Hero image or diagram]
TL;DR: [2-3 sentence summary with key takeaway]
[首图或示意图]
TL;DR: [2-3句话总结核心要点]
The Problem / Why This Matters
问题背景/为什么重要
[Set up why the reader should care — specific, not generic]
[说明读者为何需要关注——具体而非泛泛]
The Solution / How We Did It
解决方案/我们的做法
[Core content — code, architecture, explanation]
[核心内容——代码、架构、讲解]
Step 1: [First thing]
步骤1：[第一项内容]
[Explanation + code + output]
[讲解 + 代码 + 输出]
Step 2: [Second thing]
步骤2：[第二项内容]
[Explanation + code + output]
[讲解 + 代码 + 输出]
Results
成果
[Numbers, benchmarks, outcomes — be specific]
[数据、基准测试、结果——具体量化]
Trade-offs and Limitations
取舍与局限性
[Honest about downsides — builds trust]
[坦诚说明缺点——建立信任]
Conclusion
结论
[Key takeaway + what to do next]
[核心要点总结 + 下一步行动建议]
Further Reading
延伸阅读
[3-5 relevant links]
undefined[3-5个相关链接]
undefinedWord Count by Type
不同类型的字数范围
| Type | Word Count | Why |
|---|---|---|
| Quick tip | 500-800 | One concept, one example |
| Tutorial | 1,500-3,000 | Step-by-step needs detail |
| Deep dive | 2,000-4,000 | Thorough exploration |
| Architecture post | 2,000-3,500 | Diagrams carry some load |
| Benchmark | 1,500-2,500 | Data and charts do heavy lifting |
| 类型 | 字数范围 | 原因 |
|---|---|---|
| 快速技巧 | 500-800字 | 仅讲解一个概念和示例 |
| 教程 | 1500-3000字 | 分步讲解需要足够细节 |
| 深度解析 | 2000-4000字 | 需要全面探索内容 |
| 架构文章 | 2000-3500字 | 示意图可承载部分信息 |
| 基准测试 | 1500-2500字 | 数据和图表可替代大量文字 |
Diagrams and Visuals
图表与可视化
When to Use Diagrams
何时使用图表
| Scenario | Diagram Type |
|---|---|
| Request flow | Sequence diagram |
| System architecture | Box-and-arrow diagram |
| Decision logic | Flowchart |
| Data model | ER diagram |
| Performance comparison | Bar/line chart |
| Before/after | Side-by-side |
bash
undefined| 场景 | 图表类型 |
|---|---|
| 请求流程 | 时序图 |
| 系统架构 | 框线图 |
| 决策逻辑 | 流程图 |
| 数据模型 | ER图 |
| 性能对比 | 柱状图/折线图 |
| 前后对比 | 并排对比图 |
bash
undefinedGenerate architecture diagram
生成架构示意图
infsh app run infsh/html-to-image --input '{
"html": "<div style="width:1200px;height:600px;background:#0f172a;display:flex;align-items:center;justify-content:center;padding:40px;font-family:system-ui;color:white"><div style="display:flex;gap:40px;align-items:center"><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Client</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">React App</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #3b82f6;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Edge</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">CDN Cache</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">API</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">Node.js</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Database</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">PostgreSQL</p></div></div></div>"
}'
infsh app run infsh/html-to-image --input '{
"html": "<div style="width:1200px;height:600px;background:#0f172a;display:flex;align-items:center;justify-content:center;padding:40px;font-family:system-ui;color:white"><div style="display:flex;gap:40px;align-items:center"><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Client</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">React App</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #3b82f6;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Edge</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">CDN Cache</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">API</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">Node.js</p></div><div style="color:#64748b;font-size:32px">→</div><div style="background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px"><p style="font-size:14px;color:#94a3b8;margin:0">Database</p><p style="font-size:18px;font-weight:bold;margin:8px 0 0">PostgreSQL</p></div></div></div>"
}'
Generate benchmark chart
生成基准测试图表
infsh app run infsh/python-executor --input '{
"code": "import matplotlib.pyplot as plt\nimport matplotlib\nmatplotlib.use("Agg")\n\nfig, ax = plt.subplots(figsize=(12, 6))\nfig.patch.set_facecolor("#0f172a")\nax.set_facecolor("#0f172a")\n\ntools = ["Express", "Fastify", "Hono", "Elysia"]\nrps = [15000, 45000, 62000, 78000]\ncolors = ["#64748b", "#64748b", "#3b82f6", "#64748b"]\n\nax.barh(tools, rps, color=colors, height=0.5)\nfor i, v in enumerate(rps):\n ax.text(v + 1000, i, f"{v:,} req/s", va="center", color="white", fontsize=14)\n\nax.set_xlabel("Requests per second", color="white", fontsize=14)\nax.set_title("HTTP Framework Benchmark (Hello World)", color="white", fontsize=18, fontweight="bold")\nax.tick_params(colors="white", labelsize=12)\nax.spines["top"].set_visible(False)\nax.spines["right"].set_visible(False)\nax.spines["bottom"].set_color("#334155")\nax.spines["left"].set_color("#334155")\nplt.tight_layout()\nplt.savefig("benchmark.png", dpi=150, facecolor="#0f172a")\nprint("Saved")"
}'
undefinedinfsh app run infsh/python-executor --input '{
"code": "import matplotlib.pyplot as plt\nimport matplotlib\nmatplotlib.use("Agg")\n\nfig, ax = plt.subplots(figsize=(12, 6))\nfig.patch.set_facecolor("#0f172a")\nax.set_facecolor("#0f172a")\n\ntools = ["Express", "Fastify", "Hono", "Elysia"]\nrps = [15000, 45000, 62000, 78000]\ncolors = ["#64748b", "#64748b", "#3b82f6", "#64748b"]\n\nax.barh(tools, rps, color=colors, height=0.5)\nfor i, v in enumerate(rps):\n ax.text(v + 1000, i, f"{v:,} req/s", va="center", color="white", fontsize=14)\n\nax.set_xlabel("Requests per second", color="white", fontsize=14)\nax.set_title("HTTP Framework Benchmark (Hello World)", color="white", fontsize=18, fontweight="bold")\nax.tick_params(colors="white", labelsize=12)\nax.spines["top"].set_visible(False)\nax.spines["right"].set_visible(False)\nax.spines["bottom"].set_color("#334155")\nax.spines["left"].set_color("#334155")\nplt.tight_layout()\nplt.savefig("benchmark.png", dpi=150, facecolor="#0f172a")\nprint("Saved")"
}'
undefinedDistribution
内容分发
Where Developers Read
开发者的阅读平台
| Platform | Format | How to Post |
|---|---|---|
| Your blog | Full article | Primary — own your content |
| Dev.to | Cross-post (canonical URL back to yours) | Markdown import |
| Hashnode | Cross-post (canonical URL) | Markdown import |
| Hacker News | Link submission | Show HN for projects, tell HN for stories |
| Reddit (r/programming, r/webdev, etc.) | Link or discussion | Follow subreddit rules |
| Twitter/X | Thread summary + link | See twitter-thread-creation skill |
| Adapted version + link | See linkedin-content skill |
bash
undefined| 平台 | 格式 | 发布方式 |
|---|---|---|
| 自有博客 | 完整文章 | 首选——掌握内容所有权 |
| Dev.to | 交叉发布（添加规范链接指向自有博客） | Markdown导入 |
| Hashnode | 交叉发布（添加规范链接） | Markdown导入 |
| Hacker News | 链接提交 | 项目类用Show HN，故事类用tell HN |
| Reddit（r/programming、r/webdev等） | 链接或讨论 | 遵守子版块规则 |
| Twitter/X | 线程摘要+链接 | 参考twitter-thread-creation技能 |
| 改编版本+链接 | 参考linkedin-content技能 |
bash
undefinedCross-post thread to X
交叉发布线程到X
infsh app run x/post-create --input '{
"text": "New blog post: How We Reduced API Latency by 90%\n\nThe short version:\n→ Moved computation to edge\n→ Aggressive cache-control headers\n→ Eliminated N+1 queries\n\np99 went from 800ms to 90ms.\n\nFull deep dive with code: [link]"
}'
undefinedinfsh app run x/post-create --input '{
"text": "New blog post: How We Reduced API Latency by 90%\n\nThe short version:\n→ Moved computation to edge\n→ Aggressive cache-control headers\n→ Eliminated N+1 queries\n\np99 went from 800ms to 90ms.\n\nFull deep dive with code: [link]"
}'
undefinedCommon Mistakes
常见错误
| Mistake | Problem | Fix |
|---|---|---|
| No TL;DR | Busy devs leave before getting the point | 2-3 sentence summary at the top |
| Broken code examples | Destroys all credibility | Test every code block before publishing |
| No version pinning | Code breaks in 6 months | "Works with Node 20, React 18.2" |
| "Simply do X" | Dismissive, condescending | Remove "simply", "just", "easily" |
| No diagrams for architecture | Walls of text describing systems | One diagram > 500 words of description |
| Marketing tone | Developers instantly disengage | Direct, technical, honest |
| No trade-offs section | Reads as biased marketing | Always discuss downsides |
| Giant introduction before content | Readers bounce | Get to the point in 2-3 paragraphs |
| Unpinned dependencies | Tutorial breaks for future readers | Pin versions, note date written |
| No "Further Reading" | Dead end, no context | 3-5 links to deepen understanding |
| 错误 | 问题 | 修复方案 |
|---|---|---|
| 无TL;DR | 忙碌的开发者没看到重点就离开 | 在顶部添加2-3句话的摘要 |
| 代码示例无法运行 | 完全失去可信度 | 发布前测试所有代码块 |
| 未固定依赖版本 | 代码在6个月后无法运行 | 写明“适用于Node 20、React 18.2” |
| 使用“只需执行X” | 语气傲慢 condescending | 删除“只需”、“仅仅”、“轻松”等词 |
| 架构类文章无图表 | 大段文字描述系统难以理解 | 一张图表胜过500字描述 |
| 使用营销语气 | 开发者会立刻失去兴趣 | 采用直接、技术化、诚实的语气 |
| 无取舍说明部分 | 读起来像有偏见的营销内容 | 务必讨论方案的缺点 |
| 冗长的引言才进入正题 | 读者会直接退出 | 2-3段内进入核心内容 |
| 依赖未固定 | 教程对未来读者失效 | 固定版本，注明撰写日期 |
| 无“延伸阅读” | 内容无延续性 | 添加3-5个相关链接帮助读者深入理解 |
Related Skills
相关技能
bash
npx skills add inference-sh/skills@seo-content-brief
npx skills add inference-sh/skills@content-repurposing
npx skills add inference-sh/skills@og-image-designBrowse all apps:
infsh app listbash
npx skills add inference-sh/skills@seo-content-brief
npx skills add inference-sh/skills@content-repurposing
npx skills add inference-sh/skills@og-image-design浏览所有应用：
infsh app list