grove-documentation

Grove 文档写作技能

何时启用

在以下情况下启用此技能：

• 撰写帮助中心文章（Waystone）
• 起草规格说明或技术文档
• 撰写面向用户的文案（引导流程、工具提示、错误消息）
• 创建落地页文案
• 为 Grove 平台本身撰写博客文章
• 检查现有文档的语气是否一致
• 任何需要撰写用户会阅读的文字时

---

Grove 的语气

摘自项目的指导原则：

这个网站承载着真实的我——温暖、内省、酷儿，毫不掩饰地努力打造有意义的事物；请像是在帮我表达，而不是让我表演。

用深夜茶馆般的温暖和优质文档般的清晰来写——这是我的空间，要让它像家一样温馨。

Grove 的语言风格

温暖，但不卖萌。 我们友善，但不刻意表演。“我们开始吧”就很合适。“冲呀！🚀”则不合适。

直接、诚恳。 有话直说。承认局限。不要夸大其词。如果某件事目前还无法实现，就如实说明。

对话感十足，但不随意潦草。 可以使用缩略形式（you're、it's、we're）。段落要简短。可以提出邀请读者参与的问题。但表达仍要清晰，结构仍要分明。

富于内省。 Grove 为反思留出空间。我们不急于求成。除了“怎么做”，我们也会问“为什么”。

点到为止地运用诗意。 在章节末尾加上一句斜体短句，往往很有感染力。请谨慎使用，让它恰到好处。

句子节奏

长短句交替，让节奏有所变化。大声读一遍——如果听起来单调，那就是单调。

好的示例：

每一位新访客都会问同一个问题。“音乐是不是坏了？”不。这里没有音乐。以前也从来没有。

不好的示例：

每一位新访客通常都会问一个常见问题。这个问题通常是关于音乐系统是否正常运行。答案是这里没有音乐系统。以前也从来没有。

---

用户身份术语

Grove 为社区成员使用特定称谓。面向用户的文案中始终使用这些称谓。

术语	对象	使用场景
Wanderer（漫游者）	所有人	默认问候语、匿名访客、所有用户
Rooted（扎根者） / the Rooted（扎根者群体）	订阅者	已种下自己树木的人、付费用户
Pathfinder（寻路者）	可信赖的向导	受委任的社区帮手
Wayfinder（引路人）	Autumn（单数）	林地守护者

关键规则

• 面向用户的文案中，绝不要使用“用户”或“成员”。请改用“Wanderer”。
• 面向用户的文案中，绝不要使用“订阅者”。请改用“Rooted”或“the Rooted”。
• 个人邮件（第 1 天、第 3 天等）应使用 {{name}}，而不是“Wanderer”。
• 通用问候语（欢迎页、界面文案）应使用“Wanderer”。

示例

好的示例：

• “欢迎，Wanderer。”
• “感谢你继续与我们一同扎根。”
• “向 Pathfinder 求助。他们会为你指引方向。”

避免使用：

• “欢迎，用户。”
• “感谢你成为订阅者。”
• “请联系管理员。”

这种对称关系

Wanderer → Wayfinder 体现了这段旅程：

• Wanderer _寻找_道路（探索、发现路径）
• Wayfinder _指引_道路（引路、开辟路径）

完整文档请参阅 docs/grove-user-identity.md。

Grove Mode 与 GroveTerm 组件

在 UI 或内容中编写包含 Grove 术语的文本时，请使用 GroveTerm 组件，而不是将术语硬编码。Grove Mode 允许用户在标准术语（新访客的默认选项）和 Grove 术语之间切换。

对于 Svelte UI： 使用 @autumnsgrove/lattice/ui 中的 GroveTerm、GroveSwap 或 GroveText 组件。

对于数据驱动内容（FAQ 条目、定价文本、帮助文章）：使用 [[term]] 语法。示例：

• "Your [[bloom|posts]] are always yours." 在 Grove Mode 关闭时显示“posts”，开启时显示“blooms”
• "Visit your [[arbor|dashboard]] to get started." 显示“dashboard”或“Arbor”
• "Ask a [[pathfinder|community guide]] for help." 显示“community guide”或“Pathfinder”

对于 Markdown 内容（帮助中心文章）：rehype-groveterm 插件会自动转换 Markdown 中的 [[term]] 语法。

核心原则： 新访客应该看到熟悉的标准术语。Grove 的自然主题词汇由用户选择启用，而非强制使用。这样既能让平台更易于使用、更友好，也能让想要探索生态系统个性的用户获得相应体验。

---

严格避免的写法

这些写法会让文本听起来像是 AI 写的。请完全避免。

完整的反模式参考位于 owl-archive/references/anti-patterns.md。以下是最需要避免的写法摘要。

用词

• 破折号（—）： 每千词最多使用一次。请改用逗号、句号或括号。
• “不是 X，而是 Y”： 最有 AI 痕迹的句式。直接陈述即可。
• “充当”／“代表”／“标志着”： 使用简单动词。“是”就可以。
• 故作深刻的副词： 随意加入“悄然”“深刻地”“根本上”“非凡地”等词，营造虚假的深刻感。
• AI 词汇： 稳健、无缝、深入探讨、利用、织锦、格局、借助、赋能、踏上、解锁、精简、运用。

句子与段落结构

• “不是 X，不是 Y，只是 Z。” 戏剧化的层层铺垫。删掉。
• “X？就是 Y。” 自问自答式反问。删掉。
• 滥用首语重复： “他们可以……他们可以……他们可以……”反复使用相同的开头。
• 滥用三段式： 偶尔使用一次规则三段式没问题，但不要连续用三次。
• 动名词片段列表： “修复错误。编写功能。发布代码。”这类内容没有意义。
• 伪装成散文的清单： “第一……第二……第三……”用散文形式掩饰的清单。
• 单独成段的短促片段： 调整行文节奏，不要让每个句子都独占一段。

语气

• “重点来了”／“问题是”： 在普通观点前制造虚假的悬念。
• “可以把它想象成……”： 以教师口吻打比方，显得居高临下。
• “想象一下这样的世界……”： 邀请读者畅想 AI 未来。
• “我们来逐步分析”／“我们来深入探讨”： 对读者过度引导。
• 夸大其词： 并非所有事都会改变文明。
• 含糊的引述： “专家认为……”要么指出具体专家，要么直接陈述观点。
• 填充式过渡语： 此外、而且、另外、值得一提的是、尤其值得注意的是。

组织内容

• 层层摘要： 不要先说将要讲什么，接着讲内容，最后再复述一遍。
• 陈旧的隐喻： 不要重复同一个隐喻十次。用过之后就换一个。
• 堆砌历史类比： “Apple……Facebook……Stripe……Uber……”快速罗列公司名称。
• “尽管存在挑战……”： 先承认问题，再轻描淡写带过的固定句式。
• 标记式结论： “总而言之……”成熟的写作不需要宣布即将结束。
• 语义重复： 不要多次重复同一个描述。
• 泛泛的模糊措辞： AI 喜欢模棱两可，人会明确表态。说清楚你的意思。

格式

• 粗体开头的项目符号： 并非每个列表项都需要以粗体关键词开头。
• Unicode 箭头： 在文本中使用 ->，不要用 →。

---

结构指南

段落

段落要简短。每段只讲一个要点。通常两到四句话比较合适。

留白是你的朋友。密密麻麻的文字读起来可不舒服。

列表

在列表有助于理清内容时使用。但不要把所有内容都变成项目符号。有时用段落表达更流畅。

适合使用列表的情况：

• 流程中的具体步骤
• 确实并列的功能
• 便于快速查阅的信息

不适合使用列表的情况：

• 被生硬拆开的叙述性内容
• 用一句话表达读起来更好的内容

标题

具体一些。“撰写指南”比“指南”好。“Grove 的声音”比“语气”好。

面向帮助文档时，使用以行动为导向的标题效果很好：“发布你的第一篇帖子”，而不是“帖子”。

提示框

少用提示框。如果要用：

💡 提示： 有助于加深理解的实用建议。

⚠️ 警告： 忽略后可能会引发问题的事项。

不该放进提示框的内容，就直接写在正文里。

---

结尾

Grove 文档通常以一行斜体文字结尾。这句话应该水到渠成，而不是刻意为之。

合适的例子：

有时，你能给予的最激进的东西，恰恰是什么也不给。

路在行走中渐渐清晰。

不合适的例子：

这就是配置设置的方法！

如果想不到令人共鸣的诗意结尾，就别勉强。干净利落地结束也很好。

---

对酷儿友好的语言

Grove 明确对酷儿友好。这意味着：

• 不对用户的身份或关系作任何预设
• 始终使用友善、包容的语言
• 在适当的地方传达安全空间的信息
• 为我们正在打造的产品感到自豪，而不是摆出防御姿态

具体示例

避免使用	建议使用
“添加你的丈夫／妻子”	“添加你的伴侣”或“添加特别的人”
“他或她”	“他们”，或改写句子以避免使用代词
“尊敬的先生／女士”	“你好”或“嗨”
“人类”	“人们”或“所有人”
例子中只有异性伴侣	丰富例子类型，或保持中性

用户流程中的做法

如果需要询问关系信息：

• 使用开放式文本字段，而不是选项有限的下拉菜单
• 不要要求填写称谓（先生／太太／女士）
• 让人们自行描述，而不是从选项框中选择

语气

我们不会大肆宣扬自己对酷儿友好；我们本来就是如此。不搞彩虹营销，也不做表演式的盟友。包容性是融入其中的，而不是事后附加的。

---

技术文档与用户文档

规格说明和内部文档可以更直接务实。表格、架构、API 参考文档等内容，清晰比亲切更重要。

面向用户的文档（帮助中心、引导流程、错误消息）则要充分体现 Grove 的风格。

两者都应避免 AI 风格。

语气范围

API 参考文档（尽量克制亲切感，最大限度保持清晰）：

POST /api/posts

Creates a new blog post.

Parameters:
- title (string, required): Post title
- content (string, required): Markdown content
- published (boolean): Default false

Returns: Post object or 400 error

内部规格说明（清晰，略带个性）：

## Feed Caching Strategy

Feed pages cache for 5 minutes in KV. When a new post is shared,
we invalidate the chronological feed but let popular/hot feeds
age out naturally. This keeps things fresh without hammering D1.

入门指南（充分体现 Grove 的风格）：

## Your First Post

Welcome. Let's get something published.

The editor opens to a blank page. That's intentional. No templates,
no suggested topics. Just you and your words.

Write something. Anything. Hit publish when it feels ready.

引导提示（亲切简洁）：

This is your dashboard. Everything you need, nothing you don't.

---

错误消息

出错时，语气要亲切，但也要坦诚。不要责怪用户，也不要用含糊其辞的话搪塞。

错误消息原则

1. 说明发生了什么（简要说明）
2. 说明用户可以做什么（如果有办法）
3. 不要过度道歉（最多说一次“抱歉”）
4. 出问题时不要卖萌

示例

合适：

Couldn't save your post. Check your connection and try again.

That page doesn't exist. It may have been moved or deleted.

Something went wrong on our end. We're looking into it.
Your draft is saved locally.

避免：

Oops! 😅 Looks like something went wrong! Don't worry though,
these things happen! Please try again later!

Error 500: Internal Server Error. Contact administrator.

We're SO sorry!!! We feel TERRIBLE about this!!!
Please forgive us and try again!

把握平衡

坦诚说明出了什么问题。提供有帮助的后续步骤。不要让用户觉得自己很笨，也不要显得自己不专业。通常一句话就够了。

---

自我审查清单

完成任何 Grove 文档前：

• 大声读一遍。听起来像真人写的吗？
• 检查有没有破折号。删掉。
• 搜索“not just”和“but rather”。改写。
• 查找避免使用的词语。替换掉。
• 查找“serves as”“stands as”“marks a”。改得简洁些。
• 检查有没有反问式自问（“结果呢？……”）。删掉。
• 检查有没有由动名词片段组成的列表。改写成完整句子。
• 数数分号的数量。如果超过一个，就删掉一些。
• 检查有没有“Here's the thing”或“Here's where it gets interesting.”。删掉。
• 检查叙述性列表中有没有项目开头加粗的模式。取消加粗。
• 变换句子长度。不要让节奏单调。
• 删掉不必要的过渡语。让观点自然衔接。
• 结尾是否恰到好处？如果显得刻意，就删掉。
• 凌晨 2 点在茶馆里，你愿意读这篇内容吗？

---

与其他技能的集成

当 grove-ui-design 或 walking-through-the-grove 需要书面内容时，先调用这项技能。视觉设计和命名应与文风一致。

典型流程：

1. 设计工作需要新的组件或页面文案
2. 启用 grove-documentation，了解文风指导
3. 按照这些原则编写内容
4. 返回设计或命名工作

何时改用 museum-documentation

这项技能（grove-documentation）适用于简短、实用的文本：帮助文章、错误消息、工具提示、引导文案。也就是读者浏览时会读到的内容。

需要叙事性、可探索的文档时，使用 museum-documentation：

使用 grove-documentation	使用 museum-documentation
帮助中心文章	知识库“工作原理”文章
工具提示和标签	代码库导览
错误消息	系统架构说明
引导流程	面向好奇 Wanderers 的技术深度文章
快速参考指南	展览式文档

如果读者应该快速浏览并采取行动，就使用这项技能。 如果读者应该深入探索并理解，就使用 museum-documentation。

---

示例

帮助中心文章（好）

# Your First Post

Welcome. Let's get something published.

From your admin panel, click **New Post** in the sidebar. The editor opens with a blank canvas.

Write in Markdown. If you're new to it, here are the basics:

- **Bold:** `**text**`
- _Italic:_ `*text*`
- Links: `[text](url)`

The preview panel shows how your post will look. Toggle it with the eye icon.

When you're ready, hit **Publish**. Your words are live.

_The blank page isn't as scary as it looks._

帮助中心文章（差：明显的 AI 写作模式）

# Your First Post

Furthermore, in today's digital landscape, creating your first blog post is an exciting journey! It's not just about writing—it's about expressing yourself in a transformative way.

Navigate to your admin panel and leverage the New Post functionality. The seamless editor provides a robust interface for your content creation needs.

Additionally, Grove utilizes Markdown—a comprehensive formatting system that empowers you to create intricate, captivating content. Moreover, the preview feature allows you to visualize your post before publication.

Embark on your blogging journey today!

帮助中心文章（差：隐蔽的 AI 写作模式）

这个例子更棘手。乍看之下还不错：

# Your First Post

Ready to share your thoughts with the world? Let's get started.

From your admin panel, click **New Post** in the sidebar. You'll see our editor—a clean, distraction-free space for your writing.

Grove uses Markdown for formatting. It's not complicated—here are the basics you'll need:

- **Bold:** `**text**`
- _Italic:_ `*text*`
- Links: `[text](url)`

The preview panel lets you see how your post will look before publishing. When you're satisfied with your work, hit **Publish**.

Your voice matters. We can't wait to see what you create.

问题所在：

• “准备好与全世界分享你的想法了吗？”（泛泛的开场白）
• “让我们开始吧”（用得太多）
• “不受干扰的空间”（营销话术）
• “这并不复杂”（防御性缓和语气，接近“不是 X”句式）
• “当你对自己的作品感到满意时”（正式）
• “你的声音很重要。我们迫不及待地想看看你的创作。”（空洞的鼓励）

---

速查

要做	不要做
写简短的段落	写大段文字
使用“和”“但是”“所以”	使用“此外”“而且”
直说你的意思	用“可能”“也许”“或许”来含糊其辞
变换句子的节奏	让句子长度整齐划一
使用逗号或句号	使用破折号
让观点自然衔接	到处强行添加过渡语
让诗意的结尾水到渠成	强行写出诗意的结尾
承认局限	夸大其词或过度承诺

---

写作时，就像凌晨 2 点向朋友解释一件事。清晰、亲切、诚恳。