文档编写基础知识

这是一份面向学习笔记、技术说明、工具手册、项目文档的写作说明书。文档写作的目标不是堆字数，而是让读者在最短时间内理解背景、完成任务、减少误操作。

目录

• 文档写作目标
• 明确受众
• 常见文档类型
• 推荐结构
• 标题层级
• 正文写法
• 示例写法
• 配置与工具说明
• 检查清单
• markdown学习
• Latex自查表

文档写作目标

一篇有效文档通常要满足三点：

• 找得到：标题、目录、标签和关键词清楚。
• 看得懂：结构合理，术语有解释，示例能对应真实场景。
• 用得上：步骤可执行，命令可复制，检查项可验证。

写作前先回答：

1. 这篇文档解决什么问题？
2. 谁会读这篇文档？
3. 读者读完后应该能做什么？
4. 有哪些前置条件、限制或风险？

明确受众

不同读者需要不同粒度。

受众	关注点	写作重点
初学者	概念、步骤、常见错误	多解释背景，给完整示例
使用者	怎么安装、怎么配置、怎么运行	给命令、参数、排错说明
维护者	设计原因、目录结构、变更影响	给架构说明、边界条件
评审者	方案是否合理、风险是否可控	给取舍、依据、验证方式

写作时避免默认读者“已经知道”。如果某个前置知识会影响理解，应在开头说明，或链接到相关笔记，例如 markdown学习。

常见文档类型

学习笔记

用于记录概念、方法、示例和个人理解。重点是把知识组织成可复习、可链接的结构。

建议结构：

• 背景
• 核心概念
• 使用方法
• 示例
• 常见问题
• 相关链接

工具使用说明

用于说明一个工具如何安装、配置、运行和排错。重点是让读者能照着执行。

建议结构：

• 工具用途
• 环境要求
• 安装方法
• 基本命令
• 参数说明
• 示例场景
• 常见问题
• 检查清单

项目 README

用于让新读者快速理解项目。

建议结构：

• 项目简介
• 功能列表
• 环境要求
• 安装与运行
• 配置说明
• 测试方式
• 目录结构
• 常见问题

技术方案

用于说明为什么做、怎么做、风险是什么。

建议结构：

• 背景与目标
• 非目标
• 当前问题
• 方案设计
• 备选方案
• 风险与影响
• 验证方式
• 推进计划

推荐结构

通用文档可以使用以下结构：

# 文档标题
 
## 背景
 
说明为什么需要这篇文档。
 
## 目标
 
说明读者读完后应该能完成什么。
 
## 前置条件
 
- 条件 1
- 条件 2
 
## 操作步骤
 
1. 第一步
2. 第二步
3. 第三步
 
## 示例
 
给出可复制、可验证的示例。
 
## 常见问题
 
列出问题、原因、解决办法。
 
## 检查清单
 
- [ ] 检查项 1
- [ ] 检查项 2

结构不是固定模板，应根据读者任务调整。写工具手册时，“操作步骤”和“排错”更重要；写方案文档时，“取舍”和“风险”更重要。

标题层级

标题层级决定文档骨架。

# 文档标题
## 一级章节
### 二级章节
#### 三级章节

规范：

• # 只用于文档标题。
• ## 用于主要章节。
• ### 用于章节下的具体主题。
• 不跳级，例如不要从 ## 直接到 ####。
• 标题要具体，例如“安装依赖”优于“准备”，“配置数据库连接”优于“配置”。

错误示例：

# 使用说明
#### 安装
## 其他

问题：标题跳级，“其他”含义不清。

更好的写法：

# 工具名称使用说明
 
## 安装依赖
 
## 配置文件
 
## 常见问题

正文写法

先结论后细节

技术文档应优先告诉读者结论，再解释原因。

不推荐：

由于系统在启动时会读取环境变量，并且配置文件会覆盖默认值，所以这里需要注意端口设置。

推荐：

启动前需要确认 `PORT` 配置。系统会先读取默认值，再用配置文件覆盖默认值。

一段只讲一个重点

段落过长会降低可读性。每段建议围绕一个问题、一个概念或一个步骤展开。

用动词描述操作

操作步骤要使用明确动词：

• 安装依赖
• 修改配置
• 启动服务
• 查看日志
• 回滚版本

避免：

• 进行处理
• 做一下配置
• 看看情况

说明前置条件

如果步骤依赖环境、账号、权限、目录或版本，必须提前写清。

示例：

## 前置条件
 
- 已安装 Node.js 20 或更高版本。
- 当前目录为项目根目录。
- 已创建 `.env` 配置文件。

示例写法

示例是技术文档最重要的部分之一。好的示例应当能复制、能运行、能验证。

命令示例

在项目根目录运行：
 
```powershell
npm install
npm run dev
```
 
成功后，终端会显示本地访问地址。

配置示例

创建 `.env` 文件：
 
```env
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app
```
 
| 配置项 | 是否必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| PORT | 否 | 3000 | 服务监听端口 |
| DATABASE_URL | 是 | 无 | 数据库连接地址 |

错误示例与修正

错误现象：启动时报 `EADDRINUSE`。
 
原因：端口已被其他进程占用。
 
处理方式：
 
1. 修改 `PORT` 为未占用端口。
2. 或结束占用该端口的进程。

配置与工具说明

规范类、配置类、工具类文档建议包含以下信息。

工具用途

说明工具解决什么问题，以及不适合什么场景。

## 工具用途
 
该工具用于批量格式化 Markdown 文件。它不会检查事实准确性，也不会自动补充缺失内容。

环境要求

## 环境要求
 
| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| Node.js | 20+ | 运行脚本 |
| pnpm | 9+ | 安装依赖 |

参数说明

| 参数 | 是否必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| --input | 是 | 无 | 输入目录 |
| --fix | 否 | false | 是否自动修复 |

输出说明

写清执行成功后的结果，避免读者不知道是否完成。

执行成功后会生成 `dist/report.html`，并在终端输出检查通过的文件数量。

排错说明

排错内容建议用表格。

| 现象 | 可能原因 | 处理方式 |
| --- | --- | --- |
| 命令不存在 | 工具未安装或未加入 PATH | 重新安装工具并检查环境变量 |
| 权限不足 | 当前用户没有写入权限 | 切换目录或使用有权限的账号 |

Obsidian 知识库写法

在 Obsidian 中，文档不只是单篇文件，还应该和其他笔记形成关系。

推荐做法：

• 使用 [[页面名]] 连接相关主题。
• 使用 [[页面名#标题]] 链接到具体章节。
• 使用 tags 做主题分类。
• 每篇文档开头写清用途。
• 重要模板集中维护，避免多个版本互相冲突。

示例：

相关内容：
 
- [[markdown学习]]
- [[Latex自查表]]
- [[文档编写基础知识#检查清单]]

检查清单

写完文档后按以下清单检查。

结构检查

• 文档标题清楚，能说明主题。
• 开头说明了用途或背景。
• 标题层级没有跳级。
• 目录或章节顺序符合读者任务路径。
• 相关文档已用 Obsidian 双链连接。

内容检查

• 说明了目标读者和适用场景。
• 关键术语已有解释。
• 操作步骤可以按顺序执行。
• 命令、路径、配置项使用了行内代码或代码块。
• 示例可以直接复制使用。
• 常见错误给出了原因和处理方式。

格式检查

• 中文标点统一。
• 中英文、数字之间空格一致。
• 列表项表达方式一致。
• 表格列名准确，内容不过长。
• 图片有说明，路径有效。
• 外部链接可访问。

维护检查

• 文档注明了必要的版本、环境或时间信息。
• 过时内容已删除或标注。
• 模板与正文没有互相矛盾。
• 没有泄露账号、密钥、内网地址等敏感信息。

常用模板

规范文档模板

# 规范名称
 
## 目的
 
说明为什么需要这份规范。
 
## 适用范围
 
说明适用于哪些项目、角色或场景。
 
## 规则
 
### 规则一：规则名称
 
说明规则内容。
 
示例：
 
```text
正确示例
```
 
反例：
 
```text
错误示例
```
 
## 检查方式
 
- [ ] 检查项 1
- [ ] 检查项 2
 
## 例外情况
 
说明哪些场景可以不遵守，以及需要谁确认。

排错文档模板

# 问题名称排查说明
 
## 现象
 
描述用户能看到的报错、日志或异常表现。
 
## 影响范围
 
说明影响哪些功能、环境或用户。
 
## 可能原因
 
- 原因 1
- 原因 2
- 原因 3
 
## 排查步骤
 
1. 检查配置。
2. 查看日志。
3. 复现问题。
4. 验证修复。
 
## 解决办法
 
说明可执行的修复步骤。
 
## 预防措施
 
说明以后如何避免同类问题。