grove-documentation

Grove ドキュメンテーションスキル

有効にするタイミング

次の場合にこのスキルを有効にします。

• ヘルプセンターの記事（Waystone）を書くとき
• 仕様書や技術ドキュメントを作成するとき
• ユーザー向けのテキスト（オンボーディング、ツールチップ、エラーメッセージ）を書くとき
• ランディングページのコピーを作成するとき
• Grove プラットフォーム自体のブログ記事を書くとき
• 既存のドキュメントのトーンの一貫性を確認するとき
• ユーザーが読む文章を書くときはいつでも

---

Grove の声

プロジェクトの基本理念より：

このサイトは、私らしさをそのまま表現する場所です。温かく、内省的で、クィアで、意味のあるものを作ることをためらわない。演じるのではなく、私が自分の言葉で話せるよう手助けするつもりで書いてください。

真夜中のティーショップの温かさと、優れたドキュメントの明快さを込めて書いてください。ここは私の居場所です。訪れる人にも、ここを自分の家のように感じてもらいましょう。

Grove らしい語り口

温かく、でも甘ったるくしない。 親しみやすく、わざとらしくしません。「さあ、始めましょう」はしっくりきます。「さあ、行こうおおお！🚀」は違います。

率直で正直。 言いたいことをそのまま伝えます。制限があれば認めます。大げさに宣伝しません。まだ動かないものがあれば、そう伝えます。

会話調でも、雑にはしない。 短縮形を使ってもかまいません（you're、it's、we're）。段落は短めにします。読者を会話に招き入れるような問いかけも使います。それでも、明快さと構成は保ちます。

内省的。 Grove では、立ち止まって考える余地を大切にします。急がずに、「どうやって」とともに「なぜ」を問いかけます。

詩的な表現は控えめに。 セクションの最後にイタリック体で一文を添えると、心に響くことがあります。使いすぎず、ふさわしい場面で使いましょう。

文のリズム

短い文と長い文を織り交ぜ、リズムに変化をつけます。声に出して読んでみましょう。単調に聞こえるなら、実際に単調です。

良い例：

新しく訪れた人は、みな同じ質問をします。「音楽が壊れているんですか？」いいえ。音楽はありません。これまでも、ありませんでした。

良くない例：

新しく訪れた人は、よくある質問をします。たいていは、音楽システムが正常に動作しているかどうかについてです。答えは、音楽システムは存在しないということです。これまで一度も存在したことはありません。

---

ユーザーの呼び方

Grove では、コミュニティの人々を指す特定の用語を使います。ユーザー向けのテキストでは、必ずこれらの用語を使ってください。

用語	対象	文脈
Wanderer	すべての人	標準の挨拶、匿名の訪問者、すべての利用者
Rooted / the Rooted	サブスクリプション登録者	木を植えた人、有料利用者
Pathfinder	信頼されるガイド	任命されたコミュニティの支援者
Wayfinder	Autumn（単数形）	Grove の管理人

主なルール

• ユーザー向けのテキストでは、「ユーザー」や「メンバー」は決して使わないでください。代わりに「Wanderer」を使います。
• ユーザー向けのテキストでは、「サブスクリプション登録者」は決して使わないでください。代わりに「Rooted」または「the Rooted」を使います。
• 個人宛てのメール（day-1、day-3 など）では、「Wanderer」ではなく {{name}} を使います。
• 一般的な挨拶（ウェルカムページ、UI）では、「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 が OFF のときは「posts」、ON のときは「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 を参照してください。特に重要な禁止事項を以下にまとめます。

言葉の選び方

• em ダッシュ（—）： 最大で 1,000 語につき 1 つまでにしてください。カンマ、ピリオド、丸括弧を使ってください。
• 「X ではなく Y」： 最も AI らしさが出るパターンです。言いたいことをそのまま述べてください。
• 「役割を果たす」「存在感を示す」「象徴する」： シンプルな動詞を使ってください。「です」で十分です。
• 魔法のような副詞： 「静かに」「深く」「根本的に」「驚くほど」などを、重々しさを演出するために散りばめないでください。
• AI 風の語彙： 堅牢な、シームレスな、深く掘り下げる、活用する、織物、景観、駆使する、力を与える、乗り出す、解き放つ、効率化する、利用する。

文と段落の構成

• 「X ではない。Y でもない。ただ Z。」： 大げさな段階的展開です。削除してください。
• 「X とは？ Y です。」： 自分で問いかけてすぐに答える修辞疑問は削除してください。
• 照応の多用： 「できることは……できることは……できることは……」のように、同じ書き出しを繰り返さないでください。
• 三項並列の多用： 3 つ並べる表現は 1 つなら問題ありません。連続して 3 つ使わないでください。
• 動名詞の断片的な列挙： 「バグ修正。機能の開発。コードのリリース。」のような表現は何も加えません。
• コートを着たリスト記事： 「1 つ目は……2 つ目は……3 つ目は……」のように、文章に見せかけた列挙は避けてください。
• 短く印象的な断片だけの段落： 文のリズムに変化をつけてください。すべての文を段落にしないでください。

文調

• 「ここがポイントです」「実はこうです」： 特筆すべきでない内容の前に、見せかけの期待感を演出しないでください。
• 「たとえて言うなら……」： 読者を教え諭すような比喩は避けてください。
• 「こんな世界を想像してください……」： AI 的な未来への誘いは避けてください。
• 「順を追って見ていきましょう」「詳しく見ていきましょう」： 読者を必要以上に手助けしようとしないでください。
• 大げさに重要性を誇張する表現： すべてが文明を変えるわけではありません。
• 出典が曖昧な表現： 「専門家はこう主張しています……」と書くなら、専門家を明記するか、自分の主張として述べてください。
• つなぎの言葉の多用： 「さらに」「加えて」「そのうえ」「特筆すべき点として」「注目すべきことに」など。

構成

• まとめの繰り返し： これから述べることを予告し、述べた後に内容を繰り返さないでください。
• 使い古された比喩： 同じ比喩を 10 回も繰り返さないでください。一度使ったら次に進んでください。
• 歴史的な類推の積み重ね： Apple、Facebook、Stripe、Uber などの企業名を次々に並べないでください。
• 「課題はありますが……」： 問題に触れた直後に退ける定型表現は避けてください。
• 結論の予告： 「結論として……」などと書く必要はありません。しっかりした文章は、終わりを予告しなくても構いません。
• 意味上の反復： 同じ特徴を何度も繰り返さないでください。
• 曖昧な保留表現： AI は曖昧な表現を使いがちです。人間は明確に述べます。言いたいことをはっきり伝えてください。

書式

• 太字から始まる箇条書き： すべての項目を太字のキーワードから始める必要はありません。
• Unicode の矢印： 文章では -> を使い、→ は使わないでください。

---

構成上のガイドライン

段落

短くまとめます。1つの段落では、1つのことを伝えます。通常は2〜4文がちょうどよい長さです。

余白を大切にします。テキストがぎっしり詰まっていると、居心地がよくありません。

リスト

内容がわかりやすくなるときは、リストを使います。ただし、何でも箇条書きにしないでください。文章のほうが自然に読める場合もあります。

リストが効果的な例：

• 手順が明確なプロセス
• 互いに並列な機能
• すぐに参照できる情報

リストが適さない例：

• 物語のような内容を不自然に分割したもの
• 文章にしたほうが読みやすいもの

見出し

具体的にします。「ガイドライン」より「文章作成のガイドライン」、「声」より「Groveらしい語り口」のほうが適切です。

ヘルプドキュメントでは、行動を促す見出しが効果的です。「投稿」ではなく「最初の投稿を追加する」とします。

コールアウト

控えめに使います。使う場合は、次のようにします。

💡 ヒント： 理解を深めるための役立つ提案です。

⚠️ 警告： 無視すると問題が起きる可能性があります。

本文に含めればよい内容に、コールアウトを使わないでください。

---

締めくくり

Groveのドキュメントは、イタリック体の一文で終わることがよくあります。無理に付け加えるのではなく、自然に締めくくります。

よい例：

ときには、何も差し出さないことこそ、最も大胆な選択になります。

歩み続けることで、道は見えてきます。

よくない例：

これで設定の方法はおしまいです！

心に響く詩的な締めくくりが見つからない場合は、無理に入れないでください。すっきり終えるだけでも十分です。

---

クィアフレンドリーな言葉遣い

Groveは、クィアフレンドリーであることを明確に掲げています。これは、次のことを意味します。

• ユーザーのアイデンティティや人間関係を決めつけない
• 誰もが歓迎される、包摂的な言葉遣いを徹底する
• 必要に応じて、安心できる場であることを伝える
• 自分たちの取り組みに誇りを持ち、弁解がましくならない

具体例

避ける表現	代わりに使う表現
「夫／妻を追加する」	「パートナーを追加する」または「大切な人を追加する」
「彼または彼女」	「その人」または代名詞を使わない言い方にする
「拝啓、紳士淑女の皆様」	「こんにちは」または「やあ」
「人類」	「人々」または「皆さん」
異性愛カップルだけが登場する例	例に多様性を持たせるか、中立的な内容にする

ユーザーフローでの対応

人間関係について尋ねる必要がある場合は、次のようにします。

• 選択肢が限られたドロップダウンではなく、自由記述欄を使う
• 敬称（Mr／Mrs／Ms）を必須にしない
• ボックスから選ばせるのではなく、自分自身について自由に説明できるようにする

トーン

クィアフレンドリーであることを大げさにアピールしません。私たちは、ただそうあるだけです。レインボーウォッシングや、見せかけだけの連帯表明はしません。包摂性は後付けではなく、根付いています。

---

技術ドキュメントとユーザードキュメント

仕様書や内部ドキュメントは、より事実に即した簡潔な表現でもかまいません。テーブル、スキーマ、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. 謝りすぎない（「すみません」は最大1回）
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!

バランス

何が壊れたのかを正直に伝えます。次にできることをわかりやすく示します。相手に自分が愚かだと思わせないでください。自分たちが無能だと思わせる表現も避けます。通常は1文で十分です。

---

自己レビュー用チェックリスト

Grove のドキュメントを仕上げる前に、次の点を確認してください。

• 声に出して読んでみてください。人が書いたように聞こえますか？
• ダッシュを確認してください。削除します。
• 「not just」と「but rather」を検索して、書き換えてください。
• 避けるべき単語がないか確認して、置き換えてください。
• 「serves as」、「stands as」、「marks a」がないか確認して、簡潔にしてください。
• 読者に問いかける独り言（「結果は？……」など）がないか確認して、削除してください。
• 動名詞だけの断片的な箇条書きがないか確認して、きちんとした文に書き換えてください。
• コロンの数を数えてください。1つより多ければ減らします。
• 「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 を使用
ヘルプセンターの記事	ナレッジベースの「仕組み」の解説
ツールチップとラベル	コードベースのガイド付きツアー
エラーメッセージ	システムアーキテクチャの解説
オンボーディングの流れ	好奇心旺盛な Wanderer 向けの技術的な深掘り
クイックリファレンスガイド	展示形式のドキュメント

読者に流し読みして行動してもらうなら、このスキルを使用してください。 読者に探索して理解してもらうなら、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.

問題点：

• 「Ready to share your thoughts with the world?」（ありきたりな書き出し）
• 「Let's get started」（使い古された表現）
• 「distraction-free space」（マーケティング用語）
• 「It's not complicated」（弁解がましい表現。「not X」パターンに近い）
• 「When you're satisfied with your work」（堅苦しい）
• 「Your voice matters. We can't wait to see what you create.」（空虚な励まし）

---

クイックリファレンス

すること	しないこと
短い段落を書く	長い文章の塊を書く
「and」「but」「so」を使う	「Furthermore」「Moreover」を使う
言いたいことをはっきり伝える	「may」「might」「could」で曖昧にする
文のリズムに変化をつける	文の長さを均一にする
コンマやピリオドを使う	ダッシュを使う
アイデアを自然につなげる	どこにでも無理につなぎの表現を入れる
詩的な締めくくりは内容にふさわしいものにする	詩的な締めくくりを無理に付ける
制約があることを認める	過剰に宣伝したり、約束しすぎたりする

---

午前2時に友人に説明するように書いてください。明快で、温かく、誠実に。