From Clever Solutions to User-Centered AI: A Documentation Journey

This year our team opted in to Hacktoberfest with the goal of helping new contributors make documentation contributions. In an effort to make the experience as frictionless as possible, I created an AI agent that included our MCP, Mintlify rules, and Mintlify docs and we created a cookbook to contributing with our MCP.

But I felt like I could do more for our contributors since our cookbooks are fairly repeatable and something we want to focus on. Additionally, I wanted to optimize my team's workflow with AI agents, and create a better experience for our open source contributors beyond Hacktoberfest. But instead of simplicity, I ended up engineering complexity.

After a lot of debugging, reading and re-reading Mintlify's snippet documentation, and not getting the results I expected, I (finally) asked myself: Am I solving the right problem? Here's how trying to be clever almost made me miss the point entirely, and what I learned about building effective AI tools in the process.

The Problem: Too Much Copy-Paste, Not Enough Consistency

Continue's MCP cookbooks are growing fast. Every new MCP cookbook loosely follows the same structure: "What You'll Build," prerequisites, workflow options. It seemed like a waste of time copying and pasting from other guides, and it added a step of friction for contributors to complete the issue.

The "Clever" Solution: Snippets and Variables

Initially, I thought it would be useful to combine all repetitive content into a single, reusable snippet with variables.

< CookbookIntro
  setup_step_title="Set Up PostHog API Access"
  setup_step_content="Follow the instructions..."
  // ... more variables
 />

Instead of maintaining a bunch of similar sections, contributors would just fill in variables.

Except the complexity almost immediately created challenges. Mintlify's snippet system couldn't handle the nested components (Steps, Tabs, Cards).

This wasn't the only problem though. The real problem was the human side of things. I was now asking contributors to:

• Understand our custom snippet architecture
• Configure all the variables correctly
• Learn our internal conventions before writing a single word of documentation

My "solution" actually raised the barrier to entry when my goal was to lower it.

The Shift: From Automation to AI Amplification

Instead of automating the wrong thing, I tried something different. I already had the AI agent to help contributors. Why not use it with built in rules and prompts to get them running as quickly as possible.

Rules v. Prompts

AI assistants are generally made effective by two main types of input: the Prompt (User Query) and Rules (System Instruction). Understanding the difference between rules and prompts is key to getting the desired output. Prompts dictate the subject matter and the specific action the AI needs to take right now. Rules are the instructions given to the underlying model, usually invisible to the end user. It sets the foundational behavior, personality, and guardrails for the AI Assistant.

Rules: The Structural Guardrails

The MCP Cookbook rule enforces consistency automatically, ensuring every cookbook follows the same structure without contributors needing to memorize it:

"All cookbook documentation MUST follow this exact structure and order:

1. **What You'll Build** - Card component with icon="robot"
2. **What You'll Learn** - Bulleted list with exactly 3-4 learning objectives starting with "This cookbook teaches you to:"
3. **Prerequisites** - List including: primary requirement, service account, Node.js 18+, Continue CLI with active credits, additional tools
4. **Continue CLI Setup Steps** - Steps component with: Install Continue CLI, Set up CLI Account & API Key, Add service-specific secrets
5. **[Service Name] Continuous AI Workflow Options** - Card with "🚀 Fastest Path to Success" + Tabs with "⚡ Quick Start (Recommended)" and "🛠️ Manual Setup"
6. **Agent Requirements** - Accordion explaining Continue CLI Pro Plan OR own API keys
..."

The rules control the format and structure. They dictate HOW the document looks and is ordered, regardless of the topic

Prompts: The Creative Catalyst

The MCP Cookbook prompt helps contributors think through what readers actually need:

"When creating or editing cookbook documentation, the following should be addressed in the cookbook in this order, utilizing the suggested mintlify components:

**"What You'll Build" section should cover:**
- What is the end result/system the user will have built?
- What is the main workflow or automation being created?
- **Component**: Use `<Card title="What You'll Build" icon="robot">` with blank lines and proper indentation

**For "What You'll Learn" section (3-4 items) should cover:**
..."

The prompt shares the specific content to be addressed in each part of the structure. This is the WHAT, or the actual task I need to execute for this cookbook.

Think of the analogy of AI as a world-class chef: prompts are the recipe for a single dish, while rules are the chef’s job description.

Two Lessons About AI Tooling

Powering up the AI Agent in reality powers up the contributor to succeed.

1. Clever Code ≠ Good Experience

My snippet solution could have been technically elegant. It might even be a fun conference talk.

It was also user-hostile.

The AI approach is technically simpler but dramatically more effective because it works with how humans actually think and create.

2. AI's Real Power Is Amplification, Not Replacement

I initially thought: "Automate the repetitive parts so contributors can contribute without much friction."

I wasn't wrong, but my approach was.

The repetitive parts (structure, formatting, consistency) should just be enforced automatically through rules.

How to Think About AI Collaboration

These principles translate into practical habits:

• Start with user outcomes, not technical possibilities. Define success from your users' perspective.
• Play to AI's strengths. Design for guidance, structure, and clarity.
• Make AI invisible. The best tools feel natural, not artificial.

Using the AI Docs Agent to Create Cookbooks

Now, the workflow for contributors is much simpler. Once they're logged into the Hub, and they've added the Docs Agent to their account, all they need to do is run cn --config continuedev/docs-mintlify in their terminal and they're ready to go.

Once you're running our CLI, you just need to give it a prompt for a new cookbook, and you'll be more than halfway there. A sample prompt I used for the first draft of a Linear MCP cookbook using this agent:

"Follow the prompts and rules via this agent to create a new linear Linear cookbook. For the examples, you can create from the list of commands for the linear MCP..."

Final Thoughts

I started with the right question: what do contributors need to succeed? But my initial solution wasn't the best approach. In fact, even if I could get it working, it would have added complexity to the contributor experience because they'd have to understand all the variables. It would've created an obstacle.

Here's what finally clicked for me and maybe this will help you too: rules are boundaries, prompts are questions.

Another way to think about it is what decisions can be automated through rules? What decisions require human judgment guided by prompts?

It's changed how I think about code (comments are prompts to future me, linters are rules). How I give feedback (specific corrections are rules, open questions are prompts).

The documentation problem seemed specific, but in reality, it was understanding that effectiveness comes from knowing when to constrain and when to explore. Rules without prompts create rigidity. Prompts without rules can create chaos.