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/waspWasp 是一个batteries-included的全栈框架开发者用声明式的main.wasp配置配合 React、Node.js 与 Prisma 代码即可编译出完整的客户端、服务端与部署代码。而这一切能力的入口是它的官方文档——文档是新用户接触 Wasp 的第一触点直接决定了用户是否会留下来使用这个框架。本文基于 version-0.11.8 版本的写作指南该指南当前版本位于 web/docs/writingguide.md系统拆解 Wasp 团队编写技术文档的完整方法论涵盖核心写作原则、站点与页面的信息架构、语法风格规范、协作评审流程并对照仓库中的真实文档实例进行验证。读完本文你将掌握一套可直接套用的开发者文档写作规范也能从源码仓库的角度理解 Wasp 文档为何如此组织。为什么 Wasp 需要一份文档写作指南Wasp 团队在指南开篇就给出了一个直白的判断文档是新用户接触 Wasp 的第一触点first touch point是整个用户转化漏斗的顶端。如果用户倒在文档上就永远没有机会真正使用 Wasp——哪怕他们本来可能会喜欢它。因此写作不是写代码之外顺手做的事而是产品的一部分。这份指南本身也说明了它的渊源它融合了 Vue 官方文档写作指南Vue Docs Writing Guide与 Wasp 团队自己的文档写作经验保留了其中适用于 Wasp 的条目删去了不适用的部分并把示例全部替换为 Wasp 语境下的例子。指南开头还有一句著名的提醒A word of caution写文档花费的时间会远超你的预期——即使你已经预期它会花很长时间。为了尽量减轻这个过程带来的痛苦团队建议通读全文尤其重视后文的流程Processes部分。四条核心写作原则指南将整个写作哲学浓缩为四条原则它们是后续一切规则的上位依据功能在被充分文档化之前不算存在A feature doesnt exist until its well-documented。这条原则把文档从附加品提升为功能定义的一部分——没有文档的功能对用户而言就是不存在。尊重用户的认知容量cognitive capacity。用户开始阅读时带着有限的脑力脑力耗尽就停止学习。注意两个方向的规律复杂句式、一次需要同时学习多个概念、与用户实际工作无关的抽象示例会更快耗尽认知容量帮助用户持续感到聪明、强大、好奇把内容拆成可消化的小块并注意文档的阅读节奏会更慢地消耗认知容量。始终从用户视角看问题。当你彻底理解某个东西时它会变得显而易见——这就是知识的诅咒the curse of knowledge。写文档时要回忆自己当初学这个概念时首先需要知道什么需要学哪些行话哪里容易误解什么东西花了很长时间才真正 grasp好的文档应该在用户所在的地方迎接他们。先描述问题再给出解决方案。在展示某个功能怎么用之前先解释它为什么存在。否则用户没有上下文判断这条信息是否与自己相关这是不是他们遇到的问题也不知道该把新知识与哪些已有经验连接。这四条原则在仓库的文档写作中处处可见。例如 web/docs/introduction/introduction.md 先用Wasp 是一个构建现代 Web 应用的工具描述它解决的问题再用一整节secret sauce解释为什么需要编译器最后才展示main.wasp代码而 web/docs/data-model/operations/queries.md 的开篇同样是先用 Query 能解决什么问题从服务端取数据、不应修改服务端状态再讲怎么声明与实现。文档的组织架构从站点结构到页面结构Wasp 文档的组织分为两个层级页面之间的站点级组织和单个页面内部的结构。这两层分别解决用户该从哪里找到什么和用户在一个页面里怎么读的问题。站点级组织Organization of pages指南规定了整个文档站的分区每个分区都有明确的读者目标和时长约束Getting Started入门Introduction介绍提供不超过 10 分钟的整体概览说明 Wasp 解决了什么问题、为什么存在Quick Start快速开始提供 5 分钟以内的安装与启动演示应用指引结尾链接到教程及其他资源Discord、编辑器配置、newsletterEditor Setup编辑器配置提供 5 分钟以内的指引说明如何在编辑器中充分发挥 Wasp 的能力以及当前支持哪些编辑器。Tutorial教程带领用户从零构建一个简单应用。目标是让用户感到聪明、强大、好奇。教程页面必须顺序阅读其顺序取决于功能之间的依赖关系例如要查询数据库用户必须先定义数据模型。Feature pages功能页面逐一讲解 Wasp 的各个功能分为若干小节无需顺序阅读Data model数据模型深入 Wasp 的核心特性——Entities、Actions 和 QueriesAuthentication认证涵盖 Wasp 认证的方方面面Project setup项目配置讲解如何定制与配置 Wasp 项目、如何运行测试、如何设置环境变量等即构建项目时除了写代码之外会遇到的一切。Advanced Features高级特性描述其余所有功能。这类功能要么是大多数小型应用用不到、但生产级项目必然遇到的如部署、周期性任务、发送邮件要么是对所有规模应用都有用、但需要更多 Wasp 或 TypeScript 熟练度的功能如类型安全的链接。General通用包含 Wasp 语言概览与 CLI 参考。Miscellaneous其他讨论愿景、贡献方式、采集的数据以及联系方式。这套分区在仓库目录中可以直接看到当前站点 web/docs 下对应存在introduction/、tutorial/、data-model/、auth/、project/、advanced/、general/等目录其中 web/docs/advanced/jobs.md周期任务、web/docs/advanced/email.md邮件、web/docs/advanced/links.md类型安全链接正是生产级项目才需要的高级特性web/docs/general/cli.md 与 web/docs/general/spec.md 对应 General 分区web/docs/vision.md、web/docs/contributing.md、web/docs/telemetry.md、web/docs/contact.md 则对应 Miscellaneous 分区。页面内部组织Guide 与 API Reference 双段式每个功能页面被划分为两个部分Guide指南与API referenceAPI 参考。这是 Wasp 文档最核心的页面结构约定。Guide指南像讲故事一样介绍一个功能带读者一步步把功能跑起来。它覆盖功能最重要的部分但不必穷尽——目标是提供20% 的知识帮助用户处理 80% 的用例。指南几乎就是一个教程唯一区别是它可以假设读者对应用的其他部分已有一定上下文。指南中可以链接到 API reference但大多数情况下应避免提供链接时必须给出上下文让用户判断第一次阅读时该不该点进去否则很多用户会陷入链接跳转耗尽认知容量——试图在继续之前学完一个功能的每个侧面结果永远读不完指南的第一遍记住顺畅的阅读比面面俱到更重要。指南给用户足够避免挫败体验的信息即可他们之后随时可以回来深入阅读或在遇到不常见问题时去搜索。API referenceAPI 参考功能的 API 穷尽清单必须描述所有内容覆盖三个层面Wasp API例如声明本身、必填字段与可选字段JavaScript API例如导入方式、可用函数、参数等CLICLI 命令、参数及使用示例。General通用要求Guide 与 API reference 都应该**自足self-sufficient**并包含示例。撰写时始终假设读者只读其中一个——指南不需要解释功能的一切只讲最重要的部分而 API reference 必须穷尽。此外每个示例都必须用 tabs 同时给出 Wasp 支持的所有语言版本目前是 TypeScript 和 JavaScript。即使两种语言的示例完全一致也几乎总是应该用 tabs——这虽然看起来冗余但让示例面向未来future-proof也让读者确信 Wasp 没有遗忘他们所用的语言。仓库中的 web/docs/data-model/operations/queries.md 是这套双段式结构的典型样本开头是 guide 性质的Working with Queries随后用Tabs分别给出 JavaScript 与 TypeScript 下的query声明示例并以如果你想知道query声明支持的所有选项请看 API Reference收尾引导读者其姊妹篇 web/docs/data-model/operations/actions.md 甚至提供了Queries 与 Actions 的差异速读提示帮助已熟悉 Action 的读者跳过重复内容。值得补充的是在当前版本的写作指南web/docs/writingguide.md中这条规范进一步演进不要手写 Wasp Spec API 参考——Wasp 会根据 spec 包waspc/data/packages/spec中 JSDoc 注释自动生成 API 参考页面因此文档作者只需链接到自动生成页面如现有功能页面使用CardLink那样如果需要文档化自动生成参考未覆盖的内容应在 spec 包的 JSDoc 注释中补充而不是直接在文档中手写。这体现了文档写作与编译器/代码生成工具的深度耦合。语法与写作风格让文字不拖累理解指南的Grammar and writing style部分是全篇最细碎、最可直接照抄执行的规范分为风格与语法两块。风格要点Style标题应描述问题而不是解决方案。例如低效的标题是useQueryhook描述解决方案更好的标题是让 Query 数据变为响应式Making Query data reactive描述该 hook 解决的问题。用户只有在隐约知道何时、为何使用之后才会开始认真关注某个功能的讲解。当假定读者具备某知识时在开头明说并为预期的知识链接资源。尽量一次只引入一个新概念文字和代码示例都如此。有些人能同时理解多个概念但更多人会迷失——即使没迷失也会消耗更多认知容量。尽量避免特殊的提示/告诫内容块。更好的做法是把这些内容自然地融入正文例如通过扩展示例来演示边界情况。每个页面不要交织超过两条提示/告诫。如果需要更多考虑增加一个专门的注意事项caveats小节。指南应当被从头读到尾过多的提示框会压垮正在理解基础概念的读者。避免诉诸权威例如你应该做 X因为这是最佳实践。取而代之的是用示例展示某个模式造成或解决了哪些具体的人类问题。决定先教什么时考虑力量/努力比优先教授那些用相对最少的努力就能帮用户解决最大痛点或最多问题的知识。这能让学习者感到聪明、强大、好奇从而减缓认知容量消耗。Show, dont tell展示而非讲述。例如先展示useQuery的导入与用法而不是用一大段文字描述你可以把 Query 返回的数据传给useQueryhook 并从返回对象中解构出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 等。语法要点Grammar不使用 emoji讨论中除外。emoji 可爱友好但在文档中会分散注意力有些 emoji 在不同文化中含义不同还会让文档显得不专业、质量更低。不用 meme 和搞笑图片。对 emoji 的论述同样适用于 meme——读者难以在满是玩笑的文本中认真专注。避免被动语态。写 You can deploy the Wasp app...而不是 The Wasp app can be deployed...。写作与代码示例中避免缩写如用attribute而不是attr、message而不是msg除非特意引用 API 中的缩写如auth声明。标准键盘上的符号、#、可以使用。避免过多感叹号。虚假的兴奋感会让读者疏远也让文档显得不专业。直接称呼读者。不要写 We can implement a Query... 或 The user can implement a Query...要写 You can implement a Query...。文档应当直接与读者对话避免歧义我们指谁Wasp 团队读者和 Wasp 团队一起。user用户一词只用于指代你的读者正在开发的软件的用户。有时可以用第一人称复数指代组织本身例如 We support both TypeScript and JavaScript 是可以的但 Wasp supports both TypeScript and JavaScript 通常更好。避免使用过多代词。尽可能直呼其名而不是依赖前文语境这有时听起来有点怪这种时候用代词没问题但大多数情况下应该有效。引用紧随其后的示例时句末用冒号:而不是句号.。提及项目名称时优先遵循英语的普遍惯例而非项目内部品牌惯例。例如 webpack 和 npm 都违背了句子开头单词大写项目名用 Title Case缩写词大写等惯例应统一写成 Webpack and NPM避免出现 If you dont want to use Vue CLI, you can use webpack or Rollup directly by installing them via npm or Yarn. 这种混乱句子。标题不要用 Title Case。有研究表明 sentence case仅标题首单词首字母大写可读性更好也减轻了写作者要不要大写 and/with/about的记忆负担。指南同时承认当时许多标题仍是 title-case应逐步淘汰。使用牛津逗号Oxford comma写 a, b, and c 而不是 a, b and c。当前版本新增的链接规范在 0.11.8 版本基础上当前版本的 web/docs/writingguide.md 新增了Linking to pages in the docs一节专门规范文档内部链接链接其他页面时始终使用相对链接如../../overview.md除非在编写可复用片段reusable snippet绝不使用以/docs开头的绝对链接因为它会破坏版本化文档应改用对文件根绝对absolute to the file root的写法写法是从文件根/代表docs文件夹写绝对链接并带上扩展名.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。这条链接规范与仓库的版本化机制直接相关web/versioned_docs 下并存着 version-0.11.8 到 version-0.25 等多个版本的文档副本若文档内部使用绝对/docs链接在不同版本中就会解析到错误位置。这也解释了为什么写作指南本身会以版本化副本的形式存在于每个版本目录中如 web/versioned_docs/version-0.11.8/writingguide.md。内容与沟通卓越来自迭代卓越来自迭代Excellence comes from iteration。初稿总是糟糕的但写初稿是过程里至关重要的一环。你很难跳过 Bad → OK → Good → Great → Inspiring → Transcendent 这个缓慢的进阶链。发布前只需等到 Good。Vue 指南原话是社区会帮你把它推得更远。Wasp 团队坦言自己还没有这个奢侈社区还不够大但也不能在文档上投入过多时间所以 Good 就够了。这一理念可以对照仓库中写作指南自身的演进0.11.8 版本与当前版本web/docs/writingguide.md相比新增了 API 参考自动生成说明和链接规范章节——这正是在持续编辑中逐步改进文档的实例。协作流程写作、反馈与评审指南的Processes流程部分把文档写作当作一个完整的协作过程来管理而非个人行为理想情况下在实现功能之前就写文档。这能让你从用户视角审视功能更容易发现 API 的缺陷与改进潜力。如果某个东西难以解释它很可能难以理解如果难以理解也许有更好的设计方式。收到反馈时不要防御。写作与我们个人紧密相关但如果我们对帮助改进的人发脾气他们要么停止给反馈要么开始限制反馈的内容。给别人看之前先校对并用 Grammarly 之类的工具。如果展示的作品满是拼写/语法错误得到的反馈也会是关于拼写语法的而不是你的写作是否达成目标这类更有价值的意见。请求反馈时告诉评审人你想做什么、你的担忧是什么、你在权衡哪些平衡。尽量给出一个好且直接的表达方式。这能让评审聚焦在高层问题上而不是帮你改写句子。提交前多次通读并修正最好每次间隔一段时间。时间间隔能让文本脱离短期记忆帮助更客观地看待它。可以让 AI 改进文本但必须检查并修正最终版本由你签核。当有人报告问题时几乎总是存在真正的问题——即使他们提出的解决方案不一定对。继续追问以了解更多。让参与贡献/评审的人感到安全具体做法包括即使心情不好也要感谢贡献/评审例如 Great question!、Thanks for taking the time to explain.倾听并复述mirror当不确定理解是否正确时这既能验证对方的感受与体验也能确认你自己是否理解对了大量使用积极、有共情力的 emoji——永远显得有点奇怪也比显得刻薄或不耐烦好这主要适用于 Wasp 团队成员与外部贡献者交流核心团队成员彼此很熟不必过度使用表情与客套友善地传达规则/边界如果有人行为不当只用善意与成熟回应同时明确这种行为不可接受以及若继续下去将按行为准则发生什么。所有文档都必须经过评审周期最好不止一个评审人。不同的人关注不同的点有人擅长设计示例有人擅长类比和解释复杂话题有人文风清晰简洁。因此尽量让至少两三个人评审你的文档。在仓库中落地用真实文档检验规范指南的规范并非停留在纸面仓库中的文档是它最直接的检验样本。除了上文已经对照过的 web/docs/data-model/operations/queries.md、web/docs/data-model/operations/actions.md 之外还可以观察web/docs/introduction/quick-start.md 与 web/docs/introduction/editor-setup.md 严格遵循5 分钟内完成的 Getting Started 约束web/docs/tutorial 下的教程按01-create.md到07-auth.md编号排列体现功能依赖决定阅读顺序的原则web/docs/data-model/entities.md 深入 Wasp 的核心数据模型概念属于 Data model 分区web/docs/project/env-vars.md、web/docs/project/testing.md 等属于 Project setup 分区覆盖构建项目时除了编程之外的一切仓库根目录的 web/README.md 将 Writing Guide 明确列为团队风格指南The Writing Guide is our style guide说明这套规范在文档贡献流程中的强制地位。已知局限与可能的改进方向指南最后坦诚地列出了现状与展望部分文档尚未完全遵循本指南的全部规范。不需要立刻动手修复所有问题——可以在编辑这些文档时顺便慢慢改进。团队讨论过建立存放全部文档示例代码的 git 仓库。这会让代码片段的复制、粘贴、测试与维护都更简单。这两条未完成事项本身也是写作哲学的体现文档是持续演进的产物允许Good先发布再在后续迭代中逼近更高质量。结语Wasp 的文档写作指南是一份把用户体验贯彻到文字层面的工程规范从功能未文档化即不存在的产品观到尊重认知容量的心理学依据再到 Guide/API Reference 双段式结构、标题描述问题、直接称呼读者、用 tabs 覆盖 TS/JS 等可执行的细节最后以先写文档再写功能和多评审人周期收束流程。对于任何正在构建面向开发者的框架或库的团队这份指南version-0.11.8 版本与当前版本都是一份可以直接借鉴的写作规范对于 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
