Documentation (aka docs)

How to provide AI with the right documentation for better results

The Golden Rule

The more articulate you are with your needs, the better you describe the context, and the more concise you are with the information (documentation) you provide your AI with — the better results you'll get.

Pass your AI the documentation of the service (API, Library, SDK…) you're trying to use. DON'T just pass it the website's URL. Instead, create a markdown file within your project and paste a markdown version of that page and give that file to the AI.

Creating Documentation Files

File Organization

You can create a markdown file by using the file name .md (e.g. stripe-auth.md).

Important: Don't place all the documentation in the same file. Today, AI only reads ~250 lines at a time in Cursor. Many times it will lie and tell you it read the file — but it didn't or got confused because the file was too large.

Example organization for Farcaster Mini App:

farcaster-getting-started.md
farcaster-notifications.md
farcaster-context.md

Getting Markdown Documentation

1. /llms.txt Endpoints

Many sites now support /llms.txt and /llms-full.txt: Use these endpoints to get markdown versions of documentation.

Example - Farcaster docs:

Main site: miniapps.farcaster.xyz

Short version: miniapps.farcaster.xyz/llms.txt

Full version: miniapps.farcaster.xyz/llms-full.txt

2. Jina AI Markdown Converter

You can turn any webpage into markdown using:

https://r.jina.ai/YOUR_URL

Example: r.jina.ai/https://www.doodles.app

3. AI-Powered Documentation Browser

Use llml.ai — it's a doc browser that gives you markdown files and lets you ask questions.

4. Manual Conversion

If nothing else works, just select the whole page and paste it in a markdown file, or pass the URL to GPT/Claude/Gemini and say:

"Give me a markdown file of https://miniapps.farcaster.xyz/"

MCPs (Model Context Protocols)

Some providers also offer MCPs for their documentation. These give your AI up-to-date, scoped access to documentation so it only pulls what it needs.

Documentation Best Practices

✅ Do This

Create separate .md files for different sections
Keep files under 250 lines
Include relevant code examples
Use descriptive filenames (e.g., stripe-payments.md)
Update docs when APIs change

❌ Avoid This

Pasting raw URLs to AI
Creating massive single documentation files
Including outdated or irrelevant information
Copying entire documentation sites

🎯 Pro Tips

Include error handling examples
Add authentication setup instructions
Document environment variable requirements
Include working code snippets

📋 Example Workflow

1. Identify the API/service you want to use
2. Find their documentation (try /llms.txt first)
3. Break it into logical sections
4. Create separate .md files for each section
5. Test with a simple implementation
6. Refine documentation based on what worked

Using Code Examples

Apart from feeding documentation, error logs, and knowing when to push ahead and when to revert, providing AI with code examples helps a lot. Most times these are within the documents of what you are using, but if not, find a project using the same tech and provide your AI with code examples in a markdown file (example.md).

When to use examples:

When documentation is unclear or incomplete
When implementing complex integrations
When dealing with authentication flows
When working with new or experimental APIs

Ask it to learn from example.md and fix the issue.

Key Takeaways

Quality Over Quantity

Better to provide focused, relevant documentation than dump everything at once.

Stay Organized

Multiple small files work better than one large file.

Keep It Current

Update your documentation files when APIs change or you learn better approaches.