企业官网建设流程全解析

• 教程
• 文档
• 人工智能
• Vibe Coding

导读：本文基于 easy-vibe 开源教程仓库中「工程卓越」章节的《Technical Writing》专题，系统讲解技术写作的文档类型、结构规范、写作原则与维护方法。easy-vibe 本身就是一个以文档为核心的教程项目——它用 VitePress 承载 10 种语言的 80+ 交互式专题，其 README、附录与多语言文档体系正是「Docs as Code」的活样本。读完本文，你将掌握 README、API 文档、架构文档等主流文档的标准结构，学会用清晰、准确、简洁的语言写作，并懂得如何借助 LLM 提升文档质量。

0. 为什么技术文档如此重要

代码告诉计算机「怎么做」（how），文档则告诉人类「为什么」（why）。一个没有文档的项目就像一台没有说明书的电器——它能运行，但使用它全靠猜测。

好文档的价值

• 降低沟通成本：新人可以独立上手，减少反复讲解
• 保留决策上下文：记录「为什么」，而不只是「是什么」
• 提升项目可信度：好文档是开源项目的门面
• 加速协作：API 文档让前后端可以并行开发

easy-vibe 正是这一理念的践行者：README.md承担了项目门面的职责，docs/en/appendix/index.md 将 9 大知识领域组织为可检索的「知识宝库」，而llms.txt则为 AI Agent（OpenClaw、Claude、Cursor、Trae 等）提供「导航地图」，让它们能快速定位答案。这印证了文档在 AI 时代的新价值：它不仅是给人看的，也是给 Agent 看的。

1. 文档类型与结构

不同类型的文档面向不同读者、承载不同内容，结构也各有标准。原专题中的交互式组件DocStructureDemo（实现见 DocStructureDemo.vue，数据见 engineering-excellence/en.js）用可点击的模板卡片展示了 README、API 文档、架构文档三类文档的标准骨架。

1.1 常见文档类型

1.2 README 的黄金结构

一个合格的 README 应包含：

1. 项目名 + 一句话描述：3 秒内让人知道这是什么
2. 快速开始：用最少的步骤跑起来
3. 功能特性：核心卖点
4. 安装：详细的环境要求与安装步骤
5. 使用示例：可复制粘贴的代码
6. 贡献指南：如何参与
7. 许可证：法律信息

easy-vibe 的 README.md 就是这一黄金结构的完整范例：开篇即用 logo 与 banner 呈现项目名与一句话定位「Learn AI coding from zero by shipping real products」，紧接着是「快速开始」（npm install→npm run dev→ 打开http://localhost:3000）、学习路径表、贡献指南与 CC BY-NC-SA 4.0 许可证声明。它还针对不同语言读者提供了 docs-readme/en-US/README.md、docs-readme/zh-CN/README.md 等 10 个本地化版本——多语言 README 本身就是「面向读者写作」的体现。

1.3 文档结构模板

根据交互组件的模板数据，可将三类核心文档的结构归纳如下：

README 模板

• 项目名 + 一句话描述：让读者 3 秒内理解项目，示例：# MyApp+> A lightweight task management tool
• 快速开始：给出最短运行路径，通常是安装加运行命令，示例：npm install myapp→npx myapp init
• 功能特性：列出核心功能，让用户判断是否适合自己，示例：- ✅ Task board、- ✅ Team collaboration、- ✅ Data export
• 使用示例：用代码片段展示典型用法，比纯文字更清晰
• 贡献指南 + 许可证：说明如何参与及适用协议

API 文档模板

• API 概览：说明 Base URL、认证方式与公共参数，示例：Base URL: https://api.example.com/v1、Auth: Bearer Token
• 请求参数：用表格列出参数名、类型、是否必填与描述：

• 响应格式：展示成功与失败的 JSON 响应示例，如{ "code": 200, "data": { ... } }
• 错误码：列出可能的错误码及其含义，如401 - Unauthorized、404 - Resource not found、429 - Too many requests

架构文档模板

• 系统概览：概括系统目标、边界与核心约束
• 架构图：展示整体架构、模块与关系，如[Client] → [API Gateway] → [Microservice Cluster]及数据库集群
• 技术选型：说明关键技术决策并对比备选方案
• 部署架构：说明生产部署与扩容策略

2. 写作原则

2.1 清晰优先

技术写作的第一原则是清晰。模糊的表述会让读者无从下手：

<!-- 差：含糊不清 --> This function processes data. <!-- 好：具体明确 --> Converts raw order data to invoice format, including tax calculation and currency conversion.

2.2 面向读者

动笔之前先问自己：谁会读这份文档？他们需要什么信息？

• 面向初学者：解释术语、提供完整示例
• 面向资深开发者：直奔主题、提供 API 参考
• 面向非技术人员：多用类比、避免行话

easy-vibe 的附录体系正是「面向读者」的典范：同样是「API」主题，api-intro 面向入门者讲清楚 API 是什么，而api-design专题（见 docs/en/appendix/4-server-and-backend/api-design.md）则面向实践者讨论状态码、错误处理与响应结构设计。

2.3 代码示例是最好的文档

纯文字描述远不如一段可运行的代码：

<!-- 差：只有文字描述 --> Call the createUser function, passing in the username and email parameters. <!-- 好：可运行示例 --> const user = await createUser({ name: 'Zhang San', email: 'zhangsan@example.com' }) // Returns: { id: 'u_123', name: 'Zhang San', createdAt: '2025-01-15' }

一个好的示例应展示入参、调用方式和返回值（包括类型与典型字段），让读者无需猜测即可照搬。

3. 实战对比：好文档 vs 差文档

原专题通过交互式组件TechWritingPracticeDemo（实现见 TechWritingPracticeDemo.vue）提供「差写作 / 好写作」并排对比，覆盖函数注释、API 描述、更新日志三类场景。

函数注释对比

// 差：只描述「做了什么」 // Process data function process(d) { ... } // 好：解释「为什么」+ 参数与返回值 + 异常情况 /** * Convert raw order data into invoice format. * @param {Order} order - Raw order object * @returns {Invoice} Formatted invoice * @throws {ValidationError} When order data is incomplete */ function toInvoice(order) { ... }

改进要点：解释为什么而非仅仅是什么；写明参数与返回类型；描述异常情况。

API 描述对比

# 差 POST /api/users Send user data to create a user. # 好 POST /api/users Create a new user account. Request body: { "name": "Alice", // required, 2-50 chars "email": "a@b.com" // required, valid email } Success response 201: { "id": "u_123", "name": "Alice" } Error response 400: { "error": "Invalid email format" }

改进要点：提供完整的请求/响应示例；标注必填与选填字段；列出错误场景。

更新日志对比

# 差 v2.1 - fixed some bugs and added features # 好 ## v2.1.0 (2025-01-15) ### Added - Support batch export of reports in PDF format ### Fixed - Fix blank login page in Safari (#234) ### Changed - Minimum Node.js version raised from 16 to 18

改进要点：按变更类型分组；关联 issue 编号；包含版本号与日期。

3.1 提交信息规范

提交信息也是一种「写给未来开发者」的文档：

# 差 fix bug update code # 好（Conventional Commits） fix: resolve login page white screen issue on Safari feat: support batch export of PDF reports docs: update example code in API authentication section

规范的提交信息能让git log直接变成一份可读的变更历史——这在以「文档驱动」著称的 easy-vibe 社区协作中同样适用。

3.2 注释的艺术

注释的价值在于补充代码无法表达的信息：

// 差：描述「是什么」（代码本身已经表达了） // Iterate through the array for (const item of items) { ... } // 好：解释「为什么」 // Iterate in reverse because forward iteration skips the next item when deleting for (let i = items.length - 1; i >= 0; i--) { ... }

记住口诀：代码说明「是什么」，注释负责「为什么」。前者交给代码，后者交给注释。

4. 文档维护

4.1 Docs as Code：文档即代码

将文档与代码放在同一仓库、用同一套工作流管理：

• 在同一个 PR 中提交代码变更与对应的文档变更
• 用 CI 检查文档格式与链接有效性
• 文档更新与版本发布保持同步

easy-vibe 本身就是 Docs as Code 的成熟实践。查看 package.json 可以发现一整套文档工程化脚本：

• npm run dev/npm run build：基于 VitePress 的本地开发与多语言构建（scripts/build-locales.mjs）
• npm run sitemap：调用 scripts/generate-sitemap.mjs 生成站点地图，保证文档可被搜索引擎收录
• npm run lint：通过 eslint.config.js 对文档主题代码做静态检查
• npm run test：用 Node 内置测试运行器执行docs与scripts下的*.test.js测试

此外，scripts/scan-appendix-component-i18n.mjs 专门扫描附录交互组件的国际化文案，配合docs/.vitepress/theme/locales/APPENDIX_COMPONENT_I18N.md确保 10 种语言的组件文案不缺漏——这正是「用工具与流程防止文档腐烂」的工程化答案。

4.2 防止文档腐烂

easy-vibe 的多语言体系也体现了「单一事实来源」思想：每个语言目录（docs/en、docs/zh-cn、docs/ja-jp等 10 个）共用同一套知识框架，主题内容各自本地化，而公共资源（如docs/public/下的样式与图标）集中管理，避免各语言各自维护一份导致漂移。

5. AI 赋能：用 LLM 提升文档质量

LLM 在技术写作上几乎「天赋异禀」——生成文档、润色表达、翻译内容都是强项。以下三组提示词可直接复制使用。

5.1 生成 API 文档

提示词：

Based on the following Express route code, generate complete API documentation including: - Endpoint path and method - Request parameters (path params, query params, request body) and types - Success and error response examples - curl usage examples [Paste your route code]

5.2 改进技术写作

提示词：

Please improve the expression of the following technical documentation: 1. Use concise and clear language, remove redundant expressions 2. Replace passive voice with active voice 3. Keep technical terms accurate 4. Add necessary code examples Preserve the original meaning; only improve the quality of expression. [Paste your documentation content]

5.3 生成 README

提示词：

Based on the following project information, generate a high-quality README.md: - Project name: [name] - One-line description: [description] - Tech stack: [list] - Core features: [list] Must include: project introduction, quick start, features, installation steps (with code), usage examples, contributing guide, license.

AI 使用建议务必核对 AI 生成文档中的技术细节——它可能虚构不存在的 API 参数或错误的返回值。始终对照真实代码进行交叉验证。

这一建议在 easy-vibe 的文档工作流中同样成立：附录中的llms.txt（见 llms.txt）专门为 AI Agent 提供导航，但每一处命令、路径与配置都来源于仓库真实内容，并随 docs/DEPLOYMENT.md 等部署文档持续同步。

6. 总结

1. 类型匹配：不同类型的文档有不同的结构与写作风格
2. 清晰优先：具体、准确、面向读者
3. 示例驱动：好的代码示例胜过千言万语
4. 持续维护：把文档当作代码，与项目一同演进

结语写文档不是在浪费时间——而是在节省未来的时间。今天花 30 分钟写的文档，未来可能为 10 个人各省下 1 小时。好文档是你能为团队做出的最佳投资。

延伸阅读

• 写作指南：Google 的技术写作课程免费且实用
• 文档工具：VitePress、Docusaurus、GitBook 等现代文档框架（easy-vibe 即基于 VitePress 构建）
• API 文档：OpenAPI/Swagger 规范是 API 文档的行业标准
• 实践建议：先从为你自己的项目写一份好 README 开始

想深入实践？easy-vibe 的附录导航 docs/en/appendix/index.md 聚合了从计算机基础到工程卓越的完整知识体系，工程卓越专区（docs/en/appendix/9-engineering-excellence/）还包含代码质量与重构、测试策略、设计模式、开源协作等相邻专题，可与本文配合阅读，构建完整的技术写作与工程素养。

• 教程
• 文档
• 人工智能
• Vibe Coding