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/waspWasp 是一个以“全栈框架”为核心的 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 ReferenceAPI 参考。这是 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 的全部内容包括三层Wasp Spec API即 spec 构造器、必填字段与可选字段。JavaScript API如导入路径、可用函数、参数等。CLICLI 命令、参数和使用示例。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, dont 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 中的缩写如authspecattribute优于attrmessage优于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开头的绝对链接因为它们会破坏版本化文档。改用“相对于文件根部的链接”。“相对于文件根部的链接”的写法写一个绝对链接从文件根开始/代表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该文件位于./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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
