feat(appendix): 重构工程实践章节，添加交互式演示组件
## 新增组件 (14个) - CodeSmellDemo.vue: 代码异味识别演示 - DecisionMatrixDemo.vue: 决策矩阵工具 - DesignPatternCatalogDemo.vue: 设计模式目录 - DocStructureDemo.vue: 文档结构示例 - LicenseComparisonDemo.vue: 开源许可证对比 - OpenSourceWorkflowDemo.vue: 开源协作流程 - PatternPlaygroundDemo.vue: 设计模式演练场 - RefactoringDemo.vue: 重构实战演示 - SecurityChecklistDemo.vue: 安全检查清单 - TDDCycleDemo.vue: TDD 循环演示 - TechRadarDemo.vue: 技术雷达图 - TechWritingPracticeDemo.vue: 技术写作实践 - TestPyramidDemo.vue: 测试金字塔 - WebSecurityDemo.vue: Web 安全演示 ## 文档更新 (7篇) - code-quality-refactoring.md: 代码质量与重构 - design-patterns.md: 设计模式 - open-source-collaboration.md: 开源协作 - security-thinking.md: 安全思维 - technical-writing.md: 技术写作 - technology-selection.md: 技术选型 - testing-strategies.md: 测试策略 ## 其他变更 - 将 browser-as-os.md 内容合并到 computer-networks.md - 更新 .gitignore 和 theme/index.js
This commit is contained in:
sanbuphy
@@ -1,3 +1,172 @@
|
||||
# 技术文档写作
|
||||
|
||||
> 待实现
|
||||
::: tip 前言
|
||||
**你写的文档有人看吗？** 很多开发者觉得"代码能跑就行，文档以后再说"。结果就是：新人入职看不懂项目、API 对接全靠口头沟通、半年后自己都忘了当初为什么这么设计。
|
||||
|
||||
本章带你掌握技术文档写作的核心方法，让你的文档真正有人看、看得懂、用得上。
|
||||
:::
|
||||
|
||||
**这篇文章会带你学什么？**
|
||||
|
||||
| 章节 | 内容 | 核心概念 |
|
||||
|-----|------|---------|
|
||||
| **第 1 章** | 文档的类型与结构 | 不同文档的写法 |
|
||||
| **第 2 章** | 写作原则 | 清晰、准确、简洁 |
|
||||
| **第 3 章** | 实战对比 | 好文档 vs 差文档 |
|
||||
| **第 4 章** | 文档维护 | 让文档保持更新 |
|
||||
|
||||
学完本章，你将能写出结构清晰、内容准确、易于维护的技术文档。
|
||||
|
||||
---
|
||||
|
||||
## 0. 全景图：为什么技术文档重要？
|
||||
|
||||
代码告诉计算机"怎么做"，文档告诉人类"为什么这么做"。没有文档的项目就像没有说明书的电器——能用，但用起来全靠猜。
|
||||
|
||||
::: tip 好文档的价值
|
||||
- **降低沟通成本**：新人自助上手，减少重复解答
|
||||
- **保存决策上下文**：记录"为什么"，而不只是"是什么"
|
||||
- **提升项目可信度**：好文档是开源项目的门面
|
||||
- **加速协作**：API 文档让前后端并行开发
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. 文档的类型与结构
|
||||
|
||||
通过下面的交互组件，了解不同类型文档的标准结构：
|
||||
|
||||
<DocStructureDemo />
|
||||
|
||||
### 1.1 常见文档类型
|
||||
|
||||
| 文档类型 | 目标读者 | 核心内容 |
|
||||
|---------|---------|---------|
|
||||
| **README** | 所有人 | 项目是什么、怎么用、怎么贡献 |
|
||||
| **API 文档** | 接口调用方 | 端点、参数、响应、错误码 |
|
||||
| **架构文档** | 开发团队 | 系统设计、技术选型、数据流 |
|
||||
| **变更日志** | 用户/开发者 | 版本变化、新增/修复/破坏性变更 |
|
||||
| **贡献指南** | 贡献者 | 开发环境、代码规范、PR 流程 |
|
||||
|
||||
### 1.2 README 的黄金结构
|
||||
|
||||
一个好的 README 应该包含：
|
||||
|
||||
1. **项目名称 + 一句话描述**：让人 3 秒内知道这是什么
|
||||
2. **快速开始**：最少步骤跑起来
|
||||
3. **功能特性**：核心卖点
|
||||
4. **安装方式**：详细的环境要求和安装步骤
|
||||
5. **使用示例**：可复制粘贴的代码
|
||||
6. **贡献指南**：如何参与
|
||||
7. **许可证**：法律信息
|
||||
|
||||
---
|
||||
|
||||
## 2. 写作原则
|
||||
|
||||
### 2.1 清晰优先
|
||||
|
||||
```markdown
|
||||
<!-- 差：模糊不清 -->
|
||||
这个函数处理数据。
|
||||
|
||||
<!-- 好：具体明确 -->
|
||||
将原始订单数据转换为发票格式，包含税费计算和币种转换。
|
||||
```
|
||||
|
||||
### 2.2 面向读者
|
||||
|
||||
写文档前先问：**谁会读这个文档？他们需要什么信息？**
|
||||
|
||||
- 给新手写：解释术语，提供完整示例
|
||||
- 给有经验的开发者写：直奔主题，提供 API 参考
|
||||
- 给非技术人员写：用类比，避免术语
|
||||
|
||||
### 2.3 代码示例是最好的文档
|
||||
|
||||
```markdown
|
||||
<!-- 差：只有文字描述 -->
|
||||
调用 createUser 函数，传入用户名和邮箱参数。
|
||||
|
||||
<!-- 好：给出可运行的示例 -->
|
||||
const user = await createUser({
|
||||
name: '张三',
|
||||
email: 'zhangsan@example.com'
|
||||
})
|
||||
// 返回: { id: 'u_123', name: '张三', createdAt: '2025-01-15' }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 实战对比
|
||||
|
||||
通过下面的交互组件，对比好的技术写作和差的技术写作：
|
||||
|
||||
<TechWritingPracticeDemo />
|
||||
|
||||
### 3.1 Commit Message 规范
|
||||
|
||||
```
|
||||
# 差
|
||||
fix bug
|
||||
update code
|
||||
|
||||
# 好（Conventional Commits）
|
||||
fix: 修复登录页在 Safari 下白屏的问题
|
||||
feat: 支持批量导出 PDF 格式报表
|
||||
docs: 更新 API 认证章节的示例代码
|
||||
```
|
||||
|
||||
### 3.2 注释的艺术
|
||||
|
||||
```javascript
|
||||
// 差：描述"是什么"（代码已经说了）
|
||||
// 遍历数组
|
||||
for (const item of items) { ... }
|
||||
|
||||
// 好：解释"为什么"
|
||||
// 倒序遍历，因为删除元素时正序会跳过下一个
|
||||
for (let i = items.length - 1; i >= 0; i--) { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 文档维护
|
||||
|
||||
### 4.1 文档即代码
|
||||
|
||||
把文档和代码放在同一个仓库，用同样的工作流管理：
|
||||
|
||||
- 文档变更随代码一起提交 PR
|
||||
- CI 检查文档格式和链接有效性
|
||||
- 版本发布时同步更新文档
|
||||
|
||||
### 4.2 避免文档腐烂
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
|------|---------|
|
||||
| 文档过时 | 代码变更时强制更新文档（PR 检查） |
|
||||
| 无人维护 | 指定文档负责人 |
|
||||
| 内容重复 | 单一信息源，其他地方引用链接 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 总结
|
||||
|
||||
1. **类型匹配**：不同文档有不同的结构和写法
|
||||
2. **清晰优先**：具体、准确、面向读者
|
||||
3. **示例驱动**：好的代码示例胜过千言万语
|
||||
4. **持续维护**：文档即代码，随项目一起演进
|
||||
|
||||
::: tip 终极思考
|
||||
写文档不是浪费时间，而是**节省未来的时间**。你今天花 30 分钟写的文档，可能帮 10 个人各节省 1 小时。好的文档是对团队最好的投资。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 延伸阅读
|
||||
|
||||
- **写作指南**：Google 的技术写作课程（Technical Writing）免费且实用。
|
||||
- **文档工具**：VitePress、Docusaurus、GitBook 等现代文档框架。
|
||||
- **API 文档**：OpenAPI/Swagger 规范是 API 文档的行业标准。
|
||||
- **实践建议**：从给自己的项目写一个好的 README 开始。
|
||||
|
||||
Reference in New Issue
Block a user