301 技术文档撰写
使用 Codex 撰写技术博客、Wiki 和产品文档，践行 Documentation-as-Code 理念
学习目标
一、技术博客撰写
从代码到文章
# 根据代码实现生成技术文章
codex write --type blog --from-code src/features/realtime-sync.ts
# 指定文章主题和受众
codex write --type blog --topic "WebSocket 实时同步实战" --audience intermediate文章结构自动生成
Codex 会生成完整的文章骨架：
- **标题和摘要**：SEO 友好的标题
- **问题背景**：为什么需要此技术方案
- **实现思路**：核心架构和关键决策
- **代码示例**：可运行的代码片段
- **性能对比**：优化前后的数据对比
- **总结和参考**：延伸阅读链接
**💡 提示：** 使用 `codex write --outline-only` 先生成大纲审阅，满意后再生成全文。
二、项目 Wiki 和知识库
项目 Wiki 生成
# 从代码仓库生成 Wiki
codex wiki --generate
# 更新已有 Wiki
codex wiki --sync
# 生成指定模块的 Wiki 页面
codex wiki --module authWiki 页面结构
Codex 自动生成以下 Wiki 页面：
| 页面 | 内容 |
|---|---|
| Home | 项目概览、快速开始 |
| Architecture | 架构图和模块说明 |
| API Reference | 接口文档和示例 |
| Development | 开发环境搭建、规范 |
| Deployment | 部署流程和配置 |
| FAQ | 常见问题自动汇总 |
三、产品文档与代码示例
产品文档生成
# 生成产品功能文档
codex docs --type product --feature "用户权限管理"
# 确保代码示例可运行
codex docs --validate-examples代码示例质量保证
Codex 在生成文档时会自动：
- 提取实际测试通过的代码片段
- 标注代码的语言和所需依赖版本
- 添加注释说明关键参数和返回值
- 提供完整的可复制运行的示例
# 验证文档中所有代码示例
codex docs --validate-examples --run四、多格式导出策略
一次编写，多格式输出
# 从同一源文件生成多种格式
codex docs --export \
--format md --output docs/ \
--format html --output site/ \
--format pdf --output dist/api-guide.pdf文档发布管道
# .github/workflows/docs.yml
name: Publish Docs
on:
push:
branches: [main]
jobs:
docs:
steps:
- uses: actions/checkout@v4
- name: Generate Docs
run: |
codex docs --export --format md,html
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
publish_dir: ./site五、Documentation-as-Code 哲学
核心理念
将文档视为与代码同等重要的一等公民：
- **版本控制**：文档与代码在同一仓库，同步版本
- **审查流程**：文档变更走同样的 PR 审查流程
- **自动化**：文档生成、验证、发布全自动化
- **可维护**：文档即 Markdown，易于编辑和协作
实践要点
# 文档编写规范检查
codex docs --lint
# 检测断链和过期引用
codex docs --check-links
# 生成文档贡献指南
codex docs --type contributing**💡 提示：** 将 `.codex/docs.yaml` 提交到仓库，确保团队使用统一的文档规范和模板。
六、本课总结
**核心要点：**
- `codex write --type blog` 将代码实现转化为技术文章
- `codex wiki --generate` 一键生成项目 Wiki
- `--validate-examples` 确保文档中的代码示例真实可运行
- 多格式导出（MD/HTML/PDF）支持不同发布渠道
- Documentation-as-Code 让文档质量与代码质量同步提升
**下一步：** 学习数据处理与分析 → [302 数据处理与分析](module4-302.md)