技术文档写作核心指南

可视化演示

展示技术文档类型体系(ADR/API/Design/Runbook)、Diátaxis四象限框架及文档度量指标体系，帮助理解技术文档的标准化管理与持续改进策略。

一、文档类型认知：先分清四张图纸

装修开工第一件事，是找物业要户型图：承重墙在哪、管道井在哪、阳台能不能封。没这张图，任何改造都是蒙眼拆墙。户型图就是房子的“架构文档”。

软件项目也有四张图纸。架构文档描述系统由哪些模块组成、模块之间如何通信、数据如何流动，读者是架构师和新成员；API 文档描述每个接口的入参、出参、错误码和示例，读者是调用方工程师；设计文档记录一个功能为什么这样设计、有哪些取舍，读者是评审者和维护者；运维手册讲怎么部署、怎么监控、出故障第一步做什么，读者是值班工程师。

四张图纸都重要，但资源有限，先写哪张？一个实用判据是：读者越多、信息失效损失越大、内容越稳定、维护成本越低的文档，越值得优先投入。把这种感觉写成分数：

想想装修：插座接口图画得越细，电工、木工、房主三方越少吵架；而墙体改造图这种半年就变一次的内容，画太细反而是负担。选文档类型，就是给自己做投入产出预算——把笔墨花在读者最多、最怕出错、最稳定的地方。

二、写作核心原则：施工规范不是漂亮话

装修队必须守着施工规范：插座离地 30 厘米、水管试压 8 公斤、瓷砖空鼓率低于 5%。没有这些数字，手艺再好的师傅也各干各的，交付的是一间“看起来能住、住起来要命”的房子。

技术文档也有四坚持。读者视角：动笔前先问谁在看、看完要做什么，像施工队长先问房主的生活习惯；准确简洁：能一句话说清不用三句，“大约 3 秒”要写成“预计 3 秒，超时阈值 5 秒”；用词统一：同一个概念全篇只有一个称呼，禁止 abort、error、failure 混用；持续更新：代码变，文档立即跟着变。

怎么量化“好读”？语言学里有一个著名的 Flesch 可读性公式，它把“句子长度”和“用词难度”折算成分数，正好对应我们说的简洁和准确：

施工规范不保证房子豪华，但保证不出人命；写作原则不保证文笔优美，但保证读者 30 秒内找到答案。把“读者视角”写入验收标准，文档才算真正交付。

三、结构设计方法：图纸的分区与编号

一栋别墅的图纸有几十张：首层平面图、二层平面图、水电系统图、节点大样图。如果没有统一图号和目录，工人找一张“次卧插座图”要翻半小时。图纸越多的项目，编号体系越重要。

文档结构设计的三件套：层级组织，按“总纲-章节-小节”组织，像楼层-房间-墙面，一个主题只在一个地方详细讲；模板规范，每类文档统一标题层级、元信息（负责人、更新日期、状态）和段落结构；导航索引，提供目录、站内搜索和相关文档链接，像楼层的逃生指示图。

信息架构有一个“七正负二定律”：人一次能轻松记住 5 到 7 个条目。假设文档有 N 个主题、每层最多放 b 个入口，那么找东西需要的层级深度是：

图纸编号体系不是束缚，而是整个施工团队的共同语言。文档的层级、模板、目录就是这套编号——让读者永远知道自己在哪、下一步去哪，而不是在文档里迷路。

四、文档即代码：预制构件的工业化思维

传统装修靠水泥砂浆现场拌、木板现场锯，工期长、误差大。装配式建筑则把楼梯、墙板做成预制构件，工厂批量生产、现场拼装，质量稳定还能追溯——这是装修业的工业化革命。

文档即代码就是把文档当成代码来管理。四个要点：版本管理，文档和代码同仓库、同分支、同 PR 评审，改代码和改文档一个流程；自动化生成，API 文档从 OpenAPI 规范或代码注释自动产出接口页面；持续发布，CI 流水线自动构建文档站点，提交即更新；一致性校验，用 linter 检查失效链接、缺失标题、术语混用。

文档最大的敌人是过期。把代码变更看作“冲击”、文档更新看作“修复”，可以用可靠性模型描述过期风险：

预制构件消灭了“现场手艺的不可控”；文档即代码消灭了“文档和代码各说各话”。把文档放进仓库、接上流水线，等于给文档装上工业化的质量护栏。

五、评审与协作：监理不是找茬

请监理不是为了刁难施工队，而是在瓷砖贴好、墙漆刷完之前发现“防水只刷了一遍”。拆一块砖的成本，比整面墙返工低一个数量级。监理是花小钱防大坑。

文档评审把监理理念搬进写作流程。评审流程：草案 → 小范围评审 → 修改 → 合并 → 发布，每次只聚焦一个问题域，拒绝三小时马拉松大会；角色分工：作者（施工队）、评审者（监理）、维护者（物业）各司其职，架构文档要架构师把关，API 文档要调用方代表亲测；反馈闭环：每条意见记录处理结果，采纳或说明理由拒绝，绝不石沉大海。

为什么评审值得投入？用缺陷发现效率说话——每投入 1 人时，能拦截多少个问题：

监理合格的标准不是“没吵过架”，而是“入住后没漏水”。评审协作的终点不是流程完备，而是文档发布后，再没有读者因为看不懂来敲你的工位。

六、度量与优化：入住回访与口碑

聪明的装修公司交付后一定会回访：入住三个月有没有渗水？电闸跳了业主会不会修？回访数据决定了下一单生意和口碑——装修不是交付即终局。

文档也需要连续度量。度量指标四件套：时效性，最后更新时间距今多久；覆盖率，多少关键功能有文档覆盖；可用性，读者能否快速找到目标；满意度，读者真实反馈。数据采集手段：站内搜索词、页面阅读时长、反馈按钮、季度问卷，像物业的报修台账。迭代改进：把指标纳入迭代排期，数据说哪份该重写就重写。

把核心指标合成一个“健康度”，团队就能一眼看到全局：

回访不是装修的尾巴，而是下一单的开始。度量让文档从“写完了”变成“在变好”，这正是文档体系和文档坟场的分水岭。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""文档健康度检查器: 扫描 docs 目录, 输出可读性, 时效性, 覆盖率指标."""import osimport reimport time  class DocHealthChecker:    """对每个 Markdown 文档计算健康度指标."""     def __init__(self, docs_dir):        self.docs_dir = docs_dir        if not os.path.isdir(docs_dir):            os.makedirs(docs_dir)            self._seed_sample_docs()        self.docs = [f for f in os.listdir(docs_dir) if f.endswith('.md')]     def _seed_sample_docs(self):        samples = {            'api.md': '## 接口说明\n\npredict 接口接收用户标识并返回推荐结果.\n\n请求参数包含用户ID与条数.\n',            'ops.md': '## 部署手册\n\n拉取镜像后启动容器, 再检查健康检查接口.\n\n如失败则查看日志并重启.\n',        }        for name, content in samples.items():            with open(os.path.join(self.docs_dir, name), 'w', encoding='utf-8') as f:                f.write(content)     def calc_readability(self, text):        """按平均句长估算可读性, 短句得分高."""        sentences = [s for s in re.split(r'[。！？\n]', text) if s.strip()]        if not sentences:            return 100.0        avg_len = sum(len(s) for s in sentences) / len(sentences)        return max(0.0, 100.0 - avg_len * 2.5)     def calc_freshness(self, path, max_age_days=90):        """距上次修改越近, 时效性越接近 1."""        age_days = (time.time() - os.path.getmtime(path)) / 86400.0        return max(0.0, 1.0 - age_days / max_age_days)     def calc_coverage(self, doc_text, code_text):        """统计代码函数名在文档中被提及的比例."""        idents = set(re.findall(r'\bdef\s+(\w+)', code_text))        if not idents:            return 1.0        covered = sum(1 for i in idents if i in doc_text)        return covered / len(idents)     def run(self, code_text=''):        print(f"== 文档健康度报告: {self.docs_dir} ==")        for name in sorted(self.docs):            path = os.path.join(self.docs_dir, name)            with open(path, encoding='utf-8') as f:                text = f.read()            readability = self.calc_readability(text)            freshness = self.calc_freshness(path)            coverage = self.calc_coverage(text, code_text) if code_text else 0.0            print(f"{name:<12} 可读性 {readability:5.1f}  时效性 {freshness:4.2f}  覆盖率 {coverage:.2f}")  if __name__ == '__main__':    demo_code = 'def predict(user_id):\n    return model(user_id)\n\ndef recall(user_id):\n    return candidates(user_id)\n'    DocHealthChecker('docs').run(demo_code)

1. self.docs = [f for f in os.listdir(docs_dir) if f.endswith('.md')]只收集 Markdown 文件作为文档候选，像清点图纸清单。
2. sentences = [s for s in re.split(r'[。！？\n]', text) if s.strip()]按中文句号和换行切句，去掉空串，句子才是可读性的基本单位。
3. avg_len = sum(len(s) for s in sentences) / len(sentences)平均句长越短，扫读体验越好，这正是 Flesch 公式的思路。
4. age_days = (time.time() - os.path.getmtime(path)) / 86400.0用文件修改时间计算文档“年龄”，86400 是一天的秒数。
5. return max(0.0, 1.0 - age_days / max_age_days)超过 90 天未更新，时效性归零，对应“过期风险”指标。
6. idents = set(re.findall(r'\bdef\s+(\w+)', code_text))用正则抓代码里所有函数名，作为覆盖率检查的“待覆盖清单”。
7. covered = sum(1 for i in idents if i in doc_text)逐一检查函数名是否在文档中被提到，得到覆盖数量。
8. DocHealthChecker('docs').run(demo_code)入口：先构造检查器（自动补样例文档），再传入示例代码跑健康度报告。

常见误区

面试题