企业官网建设流程全解析

Wasp 文档写作指南：如何为全栈框架 Wasp 编写高质量技术文档

【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp

Wasp 是一个以“全栈框架”为核心的 JavaScript/TypeScript 开发框架，其官方文档是新手接触 Wasp 的第一站。本文以仓库内web/versioned_docs/version-0.18/writingguide.md（最新版位于 web/docs/writingguide.md）为骨架，系统讲解 Wasp 文档团队沉淀出的写作原则、页面组织方法、文风语法规范与协作流程，并辅以仓库中的真实文档（如 web/docs/data-model/operations/queries.md、web/docs/auth/entities/entities.md）作为示例佐证。读完本文，你将掌握一套可直接套用的技术文档写作方法论，并能理解 Wasp 文档中Guide + API Reference双段落结构、TS/JS 双语言示例、相对链接约定等具体做法的来龙去脉。

为什么 Wasp 需要一份写作指南

Wasp 的文档是用户接触框架的第一触点，也是整个用户转化漏斗的顶端。writingguide.md开篇即点明这一立场：如果用户在文档上流失，他们可能永远不会真正使用 Wasp。这意味着文档质量直接决定框架的采用率，因此文档写作不是锦上添花，而是产品的一部分。

为此，Wasp 文档团队借鉴了 Vue 的写作指南，并结合自身写文档的实践经验，整理出这份指南。它既包含原则层面的“心法”（如尊重用户认知容量、先描述问题再给方案），也包含操作层面的“技法”（如标题用 sentence case、示例必须同时给 TypeScript 和 JavaScript 两种版本），还包含流程层面的要求（如写文档先于实现功能、多人评审）。

在深入细节之前，先记住全文最重要的警示：写文档花费的时间会超过你的预期——即便你已经预料到它会很久。为了让过程尽量顺畅，请务必通读本文的流程部分。

核心写作原则

功能没有被文档化，就等于不存在

这是 Wasp 文档写作的第一原则，也是其他所有规则的出发点。一个功能无论实现得多好，如果用户无法通过文档理解和使用它，那么这个功能对用户而言就是不存在的。这条原则决定了文档工作在产品研发中的优先级，也解释了为什么指南要求“尽可能先写文档再实现功能”。

尊重用户的认知容量

用户开始阅读时，拥有的“脑力”是有限的，用完就会停止学习。文档写作需要像管理预算一样管理用户的认知容量：

• 加速消耗认知容量的因素：复杂的长句、一次引入多个新概念、与用户实际工作无关的抽象示例。
• 减缓消耗认知容量的因素：让用户持续感到“我变聪明了、我有掌控力、我很好奇”。把内容拆解成可消化的小块、精心设计文档的叙事流，有助于让用户保持这种状态。

在 web/docs/data-model/operations/queries.md 中可以看到这种原则的实际应用：Queries 文档先讲“Queries 是什么、用来解决什么问题”，再分步骤讲解声明、实现、使用，每个步骤只聚焦一个概念，让读者始终能跟上节奏。

永远站在用户视角（对抗“知识的诅咒”）

当你彻底理解某个概念后，它对你而言会变得显而易见，这时就中了“知识的诅咒”。为了写出好文档，你需要回忆自己当初学这个概念时：

• 需要掌握哪些术语？
• 当时误解了什么？
• 哪些地方花了很长时间才真正搞懂？

好文档要“在用户所在的地方迎接用户”。指南还建议在写作过程中，先尝试向身边的人当面讲解这个概念，这会帮你快速暴露盲区。

先描述问题，再给出解决方案

在展示某个功能如何工作之前，必须先解释它为什么存在。否则用户缺少判断依据：这信息对我重要吗（这是我遇到的问题吗）？我应该把它和我已有的什么知识/经验联系起来？

这也是 Wasp 文档“Guide”段落的核心组织方式——它像讲故事一样，先让读者意识到问题的存在，再引导他们一步步解决问题。

文档整体组织：页面级结构

Wasp 的文档按读者使用场景划分成五个层级，从“初次接触”到“深度使用”逐级深入：

Getting Started（入门）

目标是让新用户以最少的投入获得成就感：

• Introduction（介绍）：在 10 分钟内讲清 Wasp 解决的问题以及它存在的原因。
• Quick Start（快速开始）：提供不超过 5 分钟的安装 Wasp、启动示例应用的指引，结尾链接到教程和其他资源（Discord、编辑器配置、Newsletter）。
• Editor Setup（编辑器配置）：5 分钟内介绍如何在编辑器中发挥 Wasp 的最大价值，以及当前支持的编辑器。

对应文件见 web/docs/introduction/introduction.md、web/docs/introduction/quick-start.md、web/docs/introduction/editor-setup.md。

Tutorial（教程）

带领用户从零开始构建一个简单应用。教程页面的目标是让用户感到“聪明、有掌控力、好奇”，且必须按顺序阅读——页面顺序取决于功能之间的依赖关系。例如：要查询数据库，用户必须首先定义数据模型，所以实体章节一定排在查询章节之前。

Wasp 的教程位于 web/docs/tutorial 目录，从01-create.md到07-auth.md逐步推进（见 web/docs/tutorial/01-create.md）。

Feature pages（功能页面）

全面介绍 Wasp 的各项功能。各页面之间不要求顺序阅读，但页面内部要遵循“页面内组织”规则（见下一节）。功能页主要覆盖三大块：

• Data model（数据模型）：深入讲解 Wasp 的核心能力——数据模型，包括 Entities（实体）、Actions（动作）和 Queries（查询）。目录见 web/docs/data-model。
• Authentication（认证）：覆盖 Wasp 中认证的所有内容，见 web/docs/auth。
• Project setup（项目配置）：讲解如何定制和配置 Wasp 项目、如何运行测试、如何设置环境变量等，见 web/docs/project。

Advanced Features（高级功能）

描述剩余的所有功能，同样遵循“页面内组织”规则。这些功能分两类：一类是大多数小应用用不到、但生产级项目必然会遇到的（如部署、定时任务、发送邮件），另一类是各种规模的应用都可能用到、但需要更高的 Wasp 或 TypeScript 熟练度（如类型安全的链接）。

General 与 Miscellaneous（通用与杂项）

• General：包含 Wasp 语言概览和 CLI 参考。
• Miscellaneous：介绍项目愿景、贡献方式、收集的数据以及联系方式，对应仓库中的 web/docs/vision.md、web/docs/contributing.md、web/docs/telemetry.md、web/docs/contact.md。

页面内组织：Guide 与 API Reference 双段落

每个功能页面都分成两大部分：Guide（指南）和API Reference（API 参考）。这是 Wasp 文档最鲜明的结构特征。

Guide：讲述功能故事

Guide 以故事的方式介绍一个功能，带领读者一步步把它跑起来。它只需覆盖功能最重要的部分，不必面面俱到——目标是提供“20% 的知识，解决 80% 的使用场景”。

Guide 本质上几乎就是一个教程，唯一区别是它可以假设读者已了解应用的其他部分上下文。需要注意的是：

• 可以链接到 API Reference 的某些部分，但大多数情况下应避免这样做。
• 如果确实提供了链接，必须同时给出上下文，让用户判断“第一次阅读时是否应该点开这个链接”。
• 否则，许多用户会陷入“链接跳转、试图在继续前进前学完功能的每个方面”的循环，消耗殆尽认知容量，最终永远无法完成第一次通读。
• 流畅的阅读体验比详尽全面更重要。给用户足够避免挫败的信息，其余部分他们可以随时回来继续读，或者在遇到不常见问题时自行搜索。

以 web/docs/data-model/operations/queries.md 为例，其 Guide 部分依次覆盖“Queries 是什么”“如何声明”“如何实现”“如何在客户端/服务端使用”“useQuery 钩子”“错误处理”“在 Query 中使用 Entities”，每一节都能独立读懂。

API Reference：穷尽 API 细节

API Reference 必须事无巨细地描述一个功能 API 的全部内容，包括三层：

1. Wasp Spec API：即 spec 构造器、必填字段与可选字段。
2. JavaScript API：如导入路径、可用函数、参数等。
3. CLI：CLI 命令、参数和使用示例。

API Reference 必须穷尽（exhaustive），这是它与 Guide 的根本区别。同样在 web/docs/data-model/operations/queries.md 的 API Reference 部分可以看到：queryspec 的声明方式、生成的客户端/服务端函数、useQuery钩子的三个参数（queryFn、queryFnArgs、options）都被完整列出。

值得注意的是，当前版本（version-0.18 之后的演进）中，Wasp Spec API 参考不再手写，而是由 Wasp 根据 spec 包（位于 waspc/data/packages/spec）中的 JSDoc 注释自动生成到web/docs/api目录。因此文档作者应该链接到自动生成的页面，而不是手动维护；如果自动生成的参考没有覆盖某个内容，就把它补进 spec 包的 JSDoc 注释里。

两个段落的共同要求

Guide 和 API Reference 都必须自足（self-sufficient），且包含展示该功能的示例。始终假设读者只读其中一个：Guide 不需要解释功能的一切，只需讲最重要的部分；而 API Reference 必须穷尽。

另一个硬性要求是：每个示例都要用 Wasp 支持的全部语言（目前是 TypeScript 和 JavaScript）通过 tab 呈现。即使 TS 与 JS 示例没有差别，也几乎总是应该用 tab。这看起来冗余，但能让示例面向未来，并让读者确信“你没有忘记他们的语言”。在 web/docs/data-model/operations/queries.md 中，几乎每个代码示例都以 TS/JS 双 tab 形式给出。

语法与写作风格规范

风格建议

• 标题应描述问题，而不是解决方案。例如，不理想的标题是“TheuseQueryhook”（它描述的是解决方案），更好的标题是“Making Query data reactive”（它提供了useQuery钩子所解决问题的上下文）。用户在理解“什么时候、为什么使用一个功能”之前，不会认真看它的解释。
• 假设读者已知某知识时，要在开头声明，并为这些前置知识提供链接。
• 尽量一次只引入一个新概念（包括文字和代码示例）。有人能同时理解多个概念，但更多人会迷失——即使没迷失的人，认知容量也被消耗得更多。
• 尽量避免 tip/caveat 专用内容块。更可取的做法是把它们自然地融入正文（比如通过扩展示例来演示边界情况）。每页交织的 tip 和 caveat 不要超过两个；如果超过，考虑新增一个 caveats 小节。Guide 本应一口气读完，过多的提示会压垮试图理解基础概念的读者。
• 避免诉诸权威（例如“你应该做 X，因为这是最佳实践”）。相反，用示例演示某个模式造成/解决了哪些具体的人类问题。
• 决定先教什么时，思考什么知识具有最佳的“能力/努力比”。即先教那些以相对最少的努力、能帮用户解决最大痛点或最多问题的内容。
• Show, don't tell（展示而非讲述）。例如：直接展示如何导入并使用useQuery钩子，而不是抽象地描述“把 Query 返回的数据传给useQuery钩子并解构返回对象的data字段”。
• 几乎总是避免幽默，尤其是讽刺和流行文化梗，因为它们无法跨文化传播。
• 不要假设超出必要范围的高级上下文。
• 多数情况下，优先用文档内链接代替重复内容。重复对学习是必要的，但过多重复会显著增加维护成本（API 变更需要在很多地方修改）。这是一个需要小心平衡的难点。
• 具体优于泛化：<BlogPost>组件示例好于<ComponentA>。
• 贴近生活优于晦涩：<BlogPost>好于<CurrencyExchangeSettings>。
• 让内容在情感上相关：与人们有经验、在乎的事物相关的解释和示例总是更有效。
• 永远优先使用更简单的语言，而非复杂或术语化的语言。例如：
  • 用“You can begin defining an Action by declaring it in Wasp.”而不是“In order to define an Action, it must first be declared via a Wasp declaration.”
  • 用“function that returns a function”而不是“higher order function”（后者技术上更准确、更简洁，但要求读者具备不一定有的知识）。
• 避免抹杀读者努力的语言，如“easy”“just”“obviously”等。

语法规范

• 不要使用 emoji（讨论场合除外）。emoji 可爱友好，但在文档中会分散注意力，不同文化中含义不同，也会让文档显得不专业、低质量。
• 不要使用梗图和搞笑图片，理由同上。
• 避免被动语态：写“You can deploy the Wasp app...”而不是“The Wasp app can be deployed...”。
• 避免缩写（除非特意引用 API 中的缩写，如authspec）：attribute优于attr，message优于msg。标准键盘上的缩写符号（@、#、&）可以使用。
• 避免过多感叹号，虚假的热情会疏远读者。
• 直接称呼读者：说“You can implement a Query...”，而不是“We can implement a Query...”或“The user can implement a Query...”。文档应直接与读者对话，避免歧义（比如“我们”到底指 Wasp 团队还是读者与团队一起）。user一词只用于指代读者正在开发软件的使用者。有时可以用第一人称复数指代组织（Wasp），例如“We support both TypeScript and JavaScript”可以接受，但“Wasp supports both TypeScript and JavaScript”通常更好。
• 避免过多代词：尽量直呼其名而非依赖前文语境。
• 引用紧随其后的示例时，用冒号（:）结尾，而不是句号（.）。
• 引用项目名称时，优先遵循英语的通用约定，而非该项目的内部品牌约定。例如 webpack、npm 都违背了“句首大写”“项目名用 Title Case”“缩写全大写”等惯例，应统一写作“Webpack and NPM”。
• 标题不要用 Title Case。有研究表明 sentence case（只有标题第一个词的首字母大写）可读性更好，也降低了写作者的认知负担（不必纠结 “and”“with”“about” 是否大写）。指南承认当前许多标题仍是 title-case，应逐步淘汰。
• 使用牛津逗号（Oxford comma）：写“a, b, and c”而不是“a, b and c”。

内容与沟通：迭代与发布时机

• 卓越来自迭代。初稿总是差的，但写作它本身是过程的关键一环。你很难避免“差 → 可以 → 好 → 很好 → 有启发性 → 超越”的缓慢进阶。
• 只等文章达到“好”就可以发布。Vue 的指南说“社区会帮你把它推得更远”，但 Wasp 目前还没有那么大的社区红利；同时也不能在文档上投入过多时间，所以“好”就足够了。

文档写作流程

写作时机：先写文档，再实现功能

理想情况下，应该在实现功能之前写文档。这会帮你从用户视角审视功能，更容易发现 API 的缺陷和改进空间。一个实用的判断标准：如果某个东西难以解释，它很可能也难以理解；如果难以理解，也许存在更好的设计方式。

反馈与评审

• 收到反馈时不要防御。写作是非常个人化的，但如果因为别人的帮助而生气，他们会停止提供反馈，或开始限制反馈的种类。
• 在给别人看之前先校对（并使用 Grammarly）。如果你展示的作品充满拼写/语法错误，得到的反馈就只会是关于拼写/语法的，而不是关于“写作是否达成目标”这类更有价值的意见。
• 请人反馈时，告诉评审者：你试图做什么；你的担忧是什么；你正在权衡哪些平衡。
• 尽力找到一个好的、直接的表达方式，让评审者聚焦高层问题，而不是反复改写你的句子。
• 提交前多次阅读并修正文本（最好每次阅读间隔一段时间）。时间间隔能让文本脱离短期记忆，帮助你更客观地看待它。
• 可以用 AI 改进文本，但务必检查并修正，且必须由你亲自签收最终版本。
• 当有人报告问题时，几乎总是存在一个真正的问题，即使他们提出的解决方案不完全正确。持续追问，了解更多。

营造安全的提问氛围

人们在贡献/评审内容时需要感到安全：

• 感谢贡献和评审，即使你心情不佳。例如：“Great question!”“Thanks for taking the time to explain.”“This is actually intentional, but thanks for taking the time to contribute.”
• 倾听对方，并在不确定是否理解正确时复述（mirror），这既能确认对方的感受与经验，也能确认你是否理解对了他们。
• 多用积极、共情的 emoji（这主要适用于团队成员对外部贡献者；核心团队成员彼此熟悉，无需过度客套）。
• 友善地沟通规则/边界：如果有人行为不当，只用善意和成熟回应，同时明确这种行为不可接受，以及继续下去会有什么后果（依据行为准则）。

评审周期

所有文档都必须走评审流程，最好有多位评审者。不同人关注点不同：有人擅长想例子，有人擅长类比和解释复杂主题，有人文风简洁清晰。因此尽量让两到三个人评审你的文档。

文档内链接规范

Wasp 文档使用 Docusaurus 管理，链接规则直接关系到版本化文档的可用性：

• 始终使用相对链接（如../../overview.md）链接到其他页面，除非你在写可复用片段（reusable snippet）。
• 永远不要使用以/docs开头的绝对链接，因为它们会破坏版本化文档。改用“相对于文件根部的链接”。

“相对于文件根部的链接”的写法：

1. 写一个绝对链接，从文件根开始（/代表docs文件夹）。
2. 包含扩展名（如.md）。

示例：/docs/introduction应写作/introduction/introduction.md，因为该文件位于./docs/introduction/introduction.md。另一个例子：/docs/auth/entities#accessing-the-auth-fields应变成/auth/entities/entities.md#accessing-the-auth-fields，该文件位于./docs/auth/entities/entities.md（仓库中对应 web/docs/auth/entities/entities.md）。

这套约定确保了同一份文档在多个版本（仓库中的web/versioned_docs/version-0.11.8至version-0.25）之间移动时，内部链接始终指向正确位置。

与 Wasp 文档体系对照：规则如何落地

以上规则在仓库中可以得到充分印证。以 web/docs/data-model/operations/queries.md 为例：

• Guide + API Reference 结构：文档先以“你可以用 Queries 从服务器获取数据，且不应修改服务器状态”开篇（先描述问题），再给出两个示例 Query 的声明与实现（展示而非讲述），最后是穷尽式的 API Reference。
• TS/JS 双 tab 示例：声明、实现、客户端调用、服务端调用、useQuery用法、错误处理、Entities 用法全部同时给出两种语言版本。
• 标题描述问题：如“Making Query data reactive”“Using Queries on the client”等小节标题都指向用户遇到的问题场景，而非机制名称。
• 相对链接：文档内部使用../../data-model/entities.md、../../auth/overview#using-the-contextuser-object这类相对链接。

同时，仓库的web/docs目录结构完全符合指南中的组织规划：introduction/、tutorial/、data-model/、auth/、project/、advanced/、deployment/、general/等子目录与“页面级组织”章节一一对应，可以直接对照学习。

已知的改进空间

指南也坦诚列出了文档当前存在的不足：

• 部分文档并未完全遵循本指南的全部规则，无需立即动手修复全部问题，可以在编辑文档时逐步改进。
• 团队讨论过建立一个包含文档中所有示例代码的 git 仓库，让复制、粘贴、测试和维护代码片段更容易。

这两点既是 Wasp 文档的现状，也是社区贡献者可以着手的方向。

【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp