技术文档编写最佳实践

title: Title
date: YYYY-MM-DD HH:MM:SS
tags: [tag1, tag2, ...]
categories: category
1234

title: 文章标题
date: 2018-03-01 21:46:12
tags: 
  - 标签一
  - 标签二
categories: 分类名(可以自定义)

Front-matter 选项详解

Front-matter 选项中的所有内容均为非必填的。但我仍然建议至少填写 title 、urlname 和 date 的值。

配置选项	默认值	描述
title	Markdown 的文件标题	文章标题，强烈建议填写此选项
date	文件创建时的日期时间	发布时间，强烈建议填写此选项，且最好保证全局唯一
author	根 _config.yml 中的 author	文章作者
img	featureImages 中的某个值	文章特征图，推荐使用图床(腾讯云、七牛云、又拍云等)来做图片的路径.如: http://xxx.com/xxx.jpg
top	true	推荐文章（文章是否置顶），如果 top 值为 true，则会作为首页推荐文章
cover	false	v1.0.2版本新增，表示该文章是否需要加入到首页轮播封面中
coverImg	无	v1.0.2版本新增，表示该文章在首页轮播封面需要显示的图片路径，如果没有，则默认使用文章的特色图片
password	无	文章阅读密码，如果要对文章设置阅读验证密码的话，就可以设置 password 的值，该值必须是用 SHA256 加密后的密码，防止被他人识破。前提是在主题的 config.yml 中激活了 verifyPassword 选项
urlname	index	文章访问路径，需要在Hexo根目录下_config.yml文件中使用permalink: :urlname/和permalink_defaults:
urlname: index
toc	true	permalink_defaults:是否开启 TOC，可以针对某篇文章单独关闭 TOC 的功能。前提是在主题的 config.yml 中激活了 toc 选项
mathjax	false	urlname: index 是否开启数学公式支持，本文章是否开启 mathjax，且需要在主题的 _config.yml 文件中也需要开启才行
summary	无	文章摘要，自定义的文章摘要内容，如果这个属性有值，文章卡片摘要就显示这段文字，否则程序会自动截取文章的部分内容作为摘要
categories	无	文章分类，本主题的分类表示宏观上大的分类，只建议一篇文章一个分类
tags	无	文章标签，一篇文章可以多个标签
keywords	文章标题	文章关键字，SEO 时需要
reprintPolicy	cc_by	文章转载规则，可以是 cc_by, cc_by_nd, cc_by_sa, cc_by_nc, cc_by_nc_nd, cc_by_nc_sa, cc0, noreprint 或 pay 中的一个

注意:

如果 img 属性不填写的话，文章特色图会根据文章标题的 hashcode 的值取余，然后选取主题中对应的特色图片，从而达到让所有文章都的特色图各有特色。
date 的值尽量保证每篇文章是唯一的，因为本主题中 Gitalk 和 Gitment 识别 id 是通过 date 的值来作为唯一标识的。
如果要对文章设置阅读验证密码的功能，不仅要在 Front-matter 中设置采用了 SHA256 加密的 password 的值，还需要在主题的 _config.yml 中激活了配置。有些在线的 SHA256 加密的地址，可供你使用：开源中国在线工具、chahuo、站长工具。
您可以在文章 md 文件的 front-matter 中指定 reprintPolicy 来给单个文章配置转载规则

📊 2026 年更新：技术写作完全指南

原文内容整理

Front Matter 配置：

title（文章标题）
date（发布时间）
tags（标签）
categories（分类）
author（作者）
img（特征图）
keywords（关键字）
等等…

✍️ 技术写作完全指南（2026 年）

一、写作前的准备

1.1 明确写作目标

写作类型：

类型	目标	字数	耗时
教程	教会读者某项技能	3000-8000	4-8 小时
笔记	记录学习心得	1000-3000	1-2 小时
总结	复盘项目经验	2000-5000	2-4 小时
分享	技术分享演讲稿	3000-6000	3-6 小时
文档	API/产品文档	2000-10000	4-10 小时

目标读者：

✅ 初学者（需要详细步骤）
✅ 进阶者（需要深度分析）
✅ 专家（需要前沿技术）

1.2 资料收集

信息来源：

官方文档（最权威）
GitHub Issues（实际问题）
Stack Overflow（常见问题）
技术博客（实践经验）
视频教程（直观演示）
实际项目（一手经验）

收集工具：

✅ Notion/Obsidian（知识管理）
✅ Pocket（稍后阅读）
✅ 浏览器书签（快速收藏）
✅ 截图工具（Snipaste）

二、文章结构

2.1 标准结构

# 标题（吸引眼球）

## 摘要/前言（100-200 字）
- 背景介绍
- 解决的问题
- 预期收获

## 目录（可选）
1. 章节一
2. 章节二
3. 章节三

## 正文

### 一、背景介绍
- 问题来源
- 为什么重要

### 二、核心内容
- 概念解释
- 代码示例
- 实践步骤

### 三、实战案例
- 场景描述
- 解决方案
- 效果展示

### 四、总结
- 要点回顾
- 注意事项
- 延伸思考

## 参考资源
- 官方文档
- 相关文章
- 工具链接

## 关于作者
- 个人简介
- 联系方式
- 其他文章

2.2 标题技巧

好标题的特点：

✅ 具体明确（不模糊）
✅ 有吸引力（引发好奇）
✅ 包含关键词（SEO 友好）
✅ 长度适中（20-40 字）

标题模板：

类型	模板	示例
教程类	X 分钟学会 Y	《30 分钟学会 Vue 3 组合式 API》
指南类	X 完全指南	《Docker 部署完全指南》
最佳实践	X 最佳实践	《React 性能优化最佳实践》
对比类	X vs Y	《Vue 3 vs React：选型指南》
清单类	X 个技巧/方法	《10 个 Git 高效使用技巧》
问题类	如何解决 X	《如何解决内存泄漏问题》
经验类	我是如何做 X 的	《我是如何优化 API 响应时间的》

三、Front Matter 详解

3.1 必填字段

---
title: 文章标题  # 必填，20-40 字
date: 2026-03-07 12:00:00  # 必填，唯一标识
updated: 2026-03-07 12:00:00  # 推荐，最后更新时间
author: John  # 推荐，作者名
description: 文章描述（100-200 字） # 必填，SEO 和摘要
tags:  # 推荐，3-5 个标签
  - 标签 1
  - 标签 2
categories: 分类名  # 必填，1 个主分类
---

3.2 可选字段

---
# 图片相关
cover: /images/cover.jpg  # 封面图
img: /images/feature.jpg  # 特征图
coverImg: /images/banner.jpg  # 轮播封面

# SEO 相关
keywords:  # 关键词
  - 关键词 1
  - 关键词 2
  - 关键词 3

# 功能相关
top: true  # 是否置顶
toc: true  # 是否显示目录
mathjax: false  # 是否开启数学公式
password:  # 阅读密码（SHA256 加密）

# 转载规则
reprintPolicy: cc_by  # cc_by, cc_by_nd, cc_by_sa, cc_by_nc, cc0, noreprint, pay

# 自定义
urlname: how-to-write-articles  # 自定义 URL
summary: 自定义摘要  # 如果不填则自动截取
---

3.3 字段说明

字段	类型	必填	说明	示例
title	String	✅	文章标题	`Hexo 博客部署指南`
date	DateTime	✅	发布时间（唯一）	`2026-03-07 12:00:00`
updated	DateTime	⚠️	最后更新时间	`2026-03-08 10:00:00`
author	String	⚠️	作者名	`John`
description	String	✅	文章描述（SEO）	`本文介绍...`
tags	Array	⚠️	标签（3-5 个）	`['Hexo', '博客']`
categories	String	✅	分类（1 个）	`技术教程`
cover	String	⚠️	封面图路径	`/images/cover.jpg`
keywords	Array	⚠️	SEO 关键词	`['教程', '部署']`
top	Boolean	❌	是否置顶	`true`
toc	Boolean	❌	是否显示目录	`true`
reprintPolicy	String	⚠️	转载规则	`cc_by`

四、写作技巧

4.1 开篇技巧

好的开篇：

✅ 提出问题（引发共鸣）
✅ 给出承诺（读者收获）
✅ 简要介绍（文章结构）

示例：

## 前言

你是否遇到过这样的问题：
- 写了很多技术文章，但阅读量寥寥无几？
- 内容很有价值，但读者说"看不懂"？
- 花了很多时间写作，但效果不佳？

本文我将分享 5 年技术写作的经验，教你：
1. 如何写出吸引人的标题
2. 如何组织清晰的文章结构
3. 如何提高写作效率
4. 如何优化 SEO 获得更多流量

相信我，掌握这些技巧后，你的文章质量会提升 10 倍！

4.2 内容组织

MECE 原则：

✅ 相互独立（Mutually Exclusive）
✅ 完全穷尽（Collectively Exhaustive）

金字塔原理：

结论先行
以上统下
归类分组
逻辑递进

示例结构：

# 如何优化 API 性能

## 核心结论（先说结果）
通过 5 个优化手段，API 响应时间从 500ms 降至 50ms

## 优化方案（分点论述）
### 1. 数据库查询优化
- 问题：N+1 查询
- 方案：使用 JOIN
- 效果：减少 80% 查询

### 2. 引入缓存
- 问题：重复查询
- 方案：Redis 缓存
- 效果：命中率 90%

### 3. 异步处理
- 问题：同步阻塞
- 方案：消息队列
- 效果：响应时间↓60%

### 4. CDN 加速
- 问题：静态资源慢
- 方案：CDN 分发
- 效果：加载时间↓70%

### 5. 代码优化
- 问题：算法复杂度高
- 方案：优化算法
- 效果：CPU 使用↓50%

## 总结（再次强调）
综合使用以上 5 个方案，性能提升 10 倍

4.3 代码示例

好代码示例的特点：

✅ 简洁（只展示关键代码）
✅ 完整（可以运行）
✅ 有注释（解释关键逻辑）
✅ 有输出（展示运行结果）

示例：

### 示例：使用 Redis 缓存

```python
# 不好的示例（缺少注释）
def get_user(user_id):
    data = redis.get(f"user:{user_id}")
    if not data:
        data = db.query("SELECT * FROM users WHERE id = ?", user_id)
        redis.set(f"user:{user_id}", data)
    return data

# 好的示例（有注释和说明）
def get_user(user_id):
    """
    获取用户信息（带缓存）
    
    缓存策略：
    1. 先查 Redis
    2. 没有则查数据库
    3. 写入缓存（过期时间 1 小时）
    
    性能提升：
    - 缓存命中：~5ms
    - 缓存未命中：~100ms
    """
    cache_key = f"user:{user_id}"
    
    # 1. 尝试从缓存获取
    cached_data = redis.get(cache_key)
    if cached_data:
        return json.loads(cached_data)
    
    # 2. 从数据库查询
    user_data = db.query(
        "SELECT * FROM users WHERE id = ?", 
        user_id
    )
    
    # 3. 写入缓存（1 小时过期）
    redis.setex(
        cache_key, 
        3600,  # 过期时间（秒）
        json.dumps(user_data)
    )
    
    return user_data

# 使用示例
user = get_user(123)
print(f"获取用户：{user['name']}")
# 输出：获取用户：John
```

4.4 图表使用

何时使用图表：

✅ 展示数据对比
✅ 说明流程步骤
✅ 展示架构设计
✅ 对比方案优劣

图表类型：

类型	用途	工具
流程图	展示流程步骤	Mermaid、Draw.io
架构图	展示系统架构	Draw.io、Excalidraw
对比表	对比方案优劣	Markdown 表格
数据图	展示数据趋势	Chart.js、ECharts
时序图	展示交互流程	Mermaid、PlantUML

Mermaid 示例：

```mermaid
graph LR
    A[用户请求] --> B{缓存命中？}
    B -->|是 | C[返回缓存数据]
    B -->|否 | D[查询数据库]
    D --> E[写入缓存]
    E --> F[返回数据]
```

五、写作流程

5.1 标准流程

1
2
3

选题 → 大纲 → 初稿 → 修改 → 校对 → 发布
 ↓      ↓      ↓      ↓      ↓      ↓
1h     1h     3h     2h     1h     0.5h

时间分配（8.5 小时）：

选题：1 小时（确定方向）
大纲：1 小时（组织结构）
初稿：3 小时（快速写作）
修改：2 小时（优化内容）
校对：1 小时（检查错误）
发布：0.5 小时（排版部署）

5.2 高效写作技巧

技巧 1: 番茄工作法

1 2	25 分钟专注写作 + 5 分钟休息 4 个番茄后休息 15-30 分钟

技巧 2: 快速初稿

1. 不看参考，先写自己知道的
2. 不纠结措辞，快速记录想法
3. 不回头修改，写完再说
4. 完成后统一修改

技巧 3: 模板化写作

创建常用文章模板：
- 教程模板
- 笔记模板
- 总结模板
- 分享模板

每次写作直接套用，节省时间

技巧 4: 碎片化收集

1. 平时看到好内容→收藏
2. 遇到问题解决后→记录
3. 有灵感想法→记下来
4. 写作时整合素材

六、SEO 优化

6.1 关键词优化

关键词选择：

核心关键词（1-2 个）
- 文章主题
- 搜索量大
- 竞争适中
长尾关键词（3-5 个）
- 更具体
- 竞争小
- 转化高

示例：

核心关键词：Hexo 博客
长尾关键词：
- Hexo 博客部署教程
- Hexo 博客主题推荐
- Hexo 博客 SEO 优化
- Hexo 博客性能优化

6.2 标题优化

标题 SEO 技巧：

✅ 包含核心关键词
✅ 长度 20-40 字
✅ 吸引点击（数字/疑问/对比）
✅ 符合搜索意图

示例对比：

原标题	优化后	效果
Hexo 教程	《Hexo 博客部署完全指南（2026 最新版）》	⬆️ 300%
如何写作	《技术写作 5 年，我总结了这 10 个技巧》	⬆️ 500%
API 优化	《API 响应时间从 500ms 降至 50ms 的 5 个方法》	⬆️ 400%

6.3 内容优化

内部链接：

相关文章：
- [Hexo 主题推荐](./hexo-themes.md)
- [GitHub Pages 部署](./github-pages.md)
- [SEO 优化指南](./seo-guide.md)

外部链接：

1
2
3

参考资源：
- [Hexo 官方文档](https://hexo.io/)
- [GitHub 仓库](https://github.com/hexojs/hexo)

图片 ALT：

1	![Hexo 博客架构图](./hexo-architecture.png "Hexo 博客架构说明")

七、常见错误

7.1 内容错误

❌ 错误 1: 没有重点

1 2	问题：什么都想说，结果什么都没说清楚解决：一篇文章只讲一个主题

❌ 错误 2: 缺少示例

1 2	问题：纯理论，读者看不懂解决：每个观点都配示例

❌ 错误 3: 代码不能运行

1 2	问题：代码有错误，读者无法复现解决：运行测试后再发布

❌ 错误 4: 没有总结

1 2	问题：读者看完不知道收获了什么解决：文末总结要点

7.2 格式错误

❌ 错误 1: 段落过长

1 2	问题：一段 500+ 字，读者看不下去解决：每段 100-200 字，适当分段

❌ 错误 2: 没有小标题

1 2	问题：一大篇文章，找不到重点解决：每 500 字加个小标题

❌ 错误 3: 错别字连篇

1 2	问题：影响专业形象解决：发布前仔细校对

八、写作工具

8.1 编辑器

工具	特点	价格	推荐指数
Typora	简洁优雅	$14.99	⭐⭐⭐⭐⭐
VS Code	功能强大	免费	⭐⭐⭐⭐⭐
Obsidian	知识管理	免费	⭐⭐⭐⭐
Notion	在线协作	免费	⭐⭐⭐⭐

8.2 图床

服务	免费额度	速度	推荐指数
七牛云	10GB	快	⭐⭐⭐⭐⭐
阿里云 OSS	无	快	⭐⭐⭐⭐
腾讯云 COS	无	快	⭐⭐⭐⭐
Imgur	无限	慢	⭐⭐⭐

8.3 其他工具

Grammarly：语法检查
Hemingway：可读性检查
Smallpdf：PDF 工具
Tinypng：图片压缩
Canva：封面设计

📈 2026 年写作趋势

内容趋势

视频 + 文字：多媒体结合
交互式内容：可运行的代码示例
AI 辅助写作：提高效率
个性化推荐：精准推送

平台趋势

自建博客：品牌化
多平台分发：最大化影响
付费内容：知识变现
社区运营：读者互动

总结

技术写作关键点：

✅ 写作前：明确目标、收集资料
✅ 写作中：结构清晰、示例丰富
✅ 写作后：SEO 优化、多平台分发

Front Matter 必填：

title（标题）
date（时间）
description（描述）
categories（分类）
tags（标签）

高效写作：

🍅 番茄工作法
📝 模板化写作
🔄 快速初稿 + 精细修改
📚 碎片化收集

最后更新: 2026-03-07

标签: #技术写作 #FrontMatter #写作技巧 #SEO 优化 #Markdown #博客

分类: 技术/写作指南/最佳实践