| name | grove-documentation |
| description | Write documentation, help articles, specs, and user-facing text in the authentic Grove voice. Use when writing any text that users will read, updating help center content, or drafting specs. Ensures warmth, clarity, and avoidance of AI patterns. |
Grove Documentation Skill
When to Activate
Activate this skill when:
- Writing help center articles (Waystone)
- Drafting specs or technical documentation
- Writing user-facing text (onboarding, tooltips, error messages)
- Creating landing page copy
- Writing blog posts for the Grove platform itself
- Reviewing existing docs for voice consistency
- Any time you're writing words that users will read
The Grove Voice
From the project's guiding principles:
This site is my authentic voice—warm, introspective, queer, unapologetically building something meaningful; write like you're helping me speak, not perform.
Write with the warmth of a midnight tea shop and the clarity of good documentation—this is my space, make it feel like home.
What Grove Sounds Like
Warm but not cutesy. We're friendly, not performative. "Let's get started" feels right. "Let's gooo! 🚀" does not.
Direct and honest. Say what you mean. Acknowledge limitations. Don't oversell. If something doesn't work yet, say so.
Conversational but not sloppy. Contractions are fine (you're, it's, we're). Short paragraphs. Questions that invite readers in. But still clear, still structured.
Introspective. Grove makes space for reflection. We don't rush. We ask "why" alongside "how."
Poetic in small doses. Italicized one-liners at the end of sections can land beautifully. Use them sparingly, earn them.
Sentence Rhythm
Mix short sentences with longer ones. Vary your rhythm. Read it aloud—if it sounds monotonous, it is.
Good:
Every new visitor asks the same question. "Is the music broken?" No. There is no music. There never has been.
Not good:
Every new visitor asks a common question. The question is usually about whether the music system is functioning. The answer is that there is no music system. There has never been one.
User Identity Terminology
Grove uses specific terms for community members. Always use these in user-facing text.
| Term | Who | Context |
|---|
| Wanderer | Everyone | Default greeting, anonymous visitors, all users |
| Rooted / the Rooted | Subscribers | Those who've planted their tree, paid users |
| Pathfinder | Trusted guides | Appointed community helpers |
| Wayfinder | Autumn (singular) | The grove keeper |
Key Rules
- Never use "user" or "member" in user-facing text. Use "Wanderer" instead.
- Never use "subscriber" in user-facing text. Use "Rooted" or "the Rooted".
- Personal emails (day-1, day-3, etc.) should use
{{name}}, not "Wanderer".
- Generic greetings (welcome pages, UI) should use "Wanderer".
Examples
Good:
- "Welcome, Wanderer."
- "Thanks for staying rooted with us."
- "Ask a Pathfinder. They'll show you the way."
Avoid:
- "Welcome, user."
- "Thanks for being a subscriber."
- "Contact an administrator."
The Symmetry
Wanderer → Wayfinder reflects the journey:
- Wanderers seek the way (exploring, finding paths)
- The Wayfinder shows the way (guiding, creating paths)
See docs/grove-user-identity.md for full documentation.
Strict Avoidances
These patterns make text sound like AI wrote it. Avoid them completely.
Em-Dashes
Avoid em-dashes (—). One tasteful use per thousand words, maximum. Use commas, periods, or parentheses instead.
Avoid: The forest—our home—is where we gather.
Better: The forest is our home. It's where we gather.
Also fine: The forest (our home) is where we gather.
The "Not X, But Y" Pattern
This phrasing is deeply AI-coded. Avoid it entirely.
Never write:
- "It's not X, but Y"
- "It's not just X, but Y"
- "It's not merely X, but rather Y"
- "Grove isn't just a platform, it's a home"
Instead, just say the thing:
- "Grove is a home for your words."
- "This is where you belong."
Overused AI Words
These words appear in AI text at rates far higher than human writing. Avoid them:
| Category | Words to Avoid |
|---|
| Adjectives | robust, seamless, innovative, cutting-edge, transformative, intricate, captivating, comprehensive |
| Nouns | tapestry, camaraderie, realm, plethora, myriad, landscape, journey (when not literal) |
| Verbs | delve, foster, leverage, navigate, empower, embark, unlock, harness |
| Phrases | at the end of the day, in today's world, it goes without saying, needless to say |
Heavy Transition Words
These make text feel stiff and robotic:
- Furthermore
- Moreover
- Additionally
- In conclusion
- That being said
- It's worth noting that
- It's important to note
Instead: Let ideas connect naturally. Use short transitions like "And," "But," "So," "Still." Or no transition at all—just start the next thought.
Semantic Echoes
Don't repeat the same adjective or descriptor multiple times. AI does this constantly.
Bad:
Grove provides a seamless experience. The seamless integration means you can seamlessly move between features.
Good:
Grove gets out of your way. Move between features without friction.
Generic Safe Claims
AI hedges. Humans commit.
Bad: "This may help improve your workflow in many cases."
Good: "This makes your workflow faster."
Structural Guidelines
Paragraphs
Keep them short. One idea per paragraph. Two to four sentences is usually right.
White space is your friend. Dense walls of text don't feel like home.
Lists
Use lists when they clarify. But don't turn everything into bullets. Sometimes prose flows better.
Good use of lists:
- Specific steps in a process
- Features that are truly parallel
- Quick reference information
Bad use of lists:
- Narrative content broken awkwardly
- Things that would read better as a sentence
Headers
Be specific. "Writing Guidelines" is better than "Guidelines." "What Grove Sounds Like" is better than "Voice."
Action-oriented headers work well for help docs: "Add Your First Post" not "Posts."
Callouts
Use sparingly. When you do:
💡 Tip: Helpful suggestion that enhances understanding.
⚠️ Warning: Something that could cause problems if ignored.
Don't use callouts for things that should just be in the text.
Closers
Grove docs often end with an italicized line. This should feel earned, not forced.
Works:
Sometimes the most radical thing you can offer is nothing at all.
The path becomes clear by walking it.
Doesn't work:
And that's how you configure your settings!
If you can't find a poetic closer that resonates, don't force one. A clean ending is fine.
Queer-Friendly Language
Grove is explicitly queer-friendly. This means:
- No assumptions about users' identities or relationships
- Welcoming, inclusive language throughout
- Safe space messaging where appropriate
- Pride in what we're building, not defensiveness
Concrete Examples
| Avoid | Use Instead |
|---|
| "Add your husband/wife" | "Add your partner" or "Add someone special" |
| "he or she" | "they" or rephrase to avoid pronouns |
| "Dear Sir/Madam" | "Hello" or "Hi there" |
| "mankind" | "people" or "everyone" |
| Examples with only straight couples | Vary your examples, or keep them neutral |
In User Flows
When asking for relationship info (if ever needed):
- Use open text fields over dropdowns with limited options
- Don't require titles (Mr/Mrs/Ms)
- Let people describe themselves rather than selecting from boxes
Tone
We don't make a big deal of being queer-friendly. We just are. No rainbow-washing, no performative allyship. The inclusivity is baked in, not bolted on.
Technical Docs vs. User Docs
Specs and internal docs can be more matter-of-fact. Tables, schemas, API references—these need clarity over warmth.
User-facing docs (help center, onboarding, error messages) carry the full Grove voice.
Both should avoid AI patterns.
The Voice Spectrum
API Reference (minimal warmth, maximum clarity):
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
Internal Spec (clear, some personality):
## 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.
Getting Started Guide (full Grove voice):
## 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.
Onboarding Tooltip (warm but concise):
This is your dashboard. Everything you need, nothing you don't.
Error Messages
When things break, stay warm but be honest. Don't blame the user. Don't hide behind vague language.
Error Message Principles
- Say what happened (briefly)
- Say what they can do (if anything)
- Don't over-apologize (one "sorry" max)
- Don't be cute when things are broken
Examples
Good:
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.
Avoid:
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!
The Balance
Be honest about what broke. Be helpful about next steps. Don't make them feel stupid. Don't make yourself sound incompetent. One sentence is usually enough.
Self-Review Checklist
Before finalizing any Grove documentation:
Integration with Other Skills
When grove-ui-design or walking-through-the-grove need written content, invoke this skill first. The visual design and naming should match the voice.
Typical flow:
- Design calls for new component/page text
- Activate
grove-documentation for voice guidance
- Write the content following these principles
- Return to design/naming work
When to Use museum-documentation Instead
This skill (grove-documentation) is for quick, functional text: help articles, error messages, tooltips, onboarding copy. Content that's read in passing.
Use museum-documentation when you need narrative, explorable documentation:
| Use grove-documentation | Use museum-documentation |
|---|
| Help center articles | Knowledge base "how it works" |
| Tooltips and labels | Codebase guided tours |
| Error messages | System architecture explains |
| Onboarding flows | Technical deep-dives for curious Wanderers |
| Quick-reference guides | Exhibit-style documentation |
If the reader should skim and act, use this skill.
If the reader should explore and understand, use museum-documentation.
Examples
Help Center Article (Good)
# 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.*
Help Center Article (Bad - Obvious AI Patterns)
# 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!
Help Center Article (Bad - Subtle AI Patterns)
This one's trickier. It looks okay at first glance:
# 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.
What's wrong:
- "Ready to share your thoughts with the world?" (generic opener)
- "Let's get started" (overused)
- "distraction-free space" (marketing-speak)
- "It's not complicated" (defensive hedge, "not X" pattern adjacent)
- "When you're satisfied with your work" (formal)
- "Your voice matters. We can't wait to see what you create." (hollow encouragement)
Quick Reference
| Do | Don't |
|---|
| Write short paragraphs | Write walls of text |
| Use "and," "but," "so" | Use "Furthermore," "Moreover" |
| Say what you mean | Hedge with "may," "might," "could" |
| Vary sentence rhythm | Write uniform sentence lengths |
| Use commas or periods | Use em-dashes |
| Let ideas connect naturally | Force transitions everywhere |
| Earn poetic closers | Force poetic closers |
| Acknowledge limitations | Oversell or overpromise |
Write like you're explaining something to a friend at 2 AM. Clear, warm, honest.
