Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

Building on the principles from the previous lessons about how agents read your documentation, this lesson introduces specific writing and structural habits that make your documentation agent-friendly.

​
Make every page self-contained

Write every page as if the reader has never seen any other page in your documentation. That means:
  • Define terms and acronyms the first time they appear on each page
  • Include prerequisites and information about who can access features
  • Document all the steps required to complete a task
  • Don’t write “as mentioned in the overview” or “once you’ve completed the previous step” without making it clear what that refers to
  • If a page depends on something being set up first, say so explicitly at the top: “This guide assumes you’ve already authenticated. If you haven’t, see Authentication.”
Each page is a document instead of a chapter.

​
Write specific titles and descriptions

Every page must have a title and a description. These are the primary signal an agent uses to decide whether a page is relevant to a user’s question. Titles should be specific enough that their content is unambiguous:
Vague titleSpecific title
Advanced configurationConfigure rate limits for API requests
AuthenticationAuthenticate API requests with API keys
TroubleshootingFix common webhook delivery failures
Descriptions should answer “why would someone read this page?” in one concrete sentence. What task it serves and what specific topics it covers. A weak description:
“Learn about our authentication system and how to use it in your application.”
A strong description:
“Authenticate API requests using API keys. Covers generating keys, passing them in request headers, and handling 401 errors.”
The second version tells an assistant exactly what the page contains. When a user asks, “Why is my API call returning a 401?”, the assistant routes them to the right page because the description mentions 401 errors explicitly. A useful test: if you covered the title and showed only the description to someone unfamiliar with your product, could they tell what the page is about?

​
Use headings that stand alone

Headings serve as navigation aids for both humans and agents. A heading like “Part three” or “More options” tells an agent nothing about what’s in the section. A heading like “Set a retry policy for failed requests” is specific enough to match against a user’s question. Apply the same principle as titles: specific enough to stand alone.

​
Keep pages focused on one thing

A page that covers installation, configuration, and troubleshooting in one place asks an agent to extract a specific answer from a mixed-topic document. Sometimes it succeeds. Often it doesn’t. If users frequently need multiple topics together, link between them rather than combining them. The navigation overhead is lower than the cost of imprecise agent responses. If your site has many mixed-topic pages, start revising your highest-traffic pages and the ones most often surfaced in support tickets. You can improve your documentation over time, starting with the pages that are most important to your users.

​
Use consistent terminology

Pick one name for each concept and use it everywhere. This is especially important for:
  • Product features and UI elements
  • Role names and permissions
  • Core concepts your users must understand to succeed with your product
If you’ve used multiple terms for the same thing in the past, add a terminology section to your CLAUDE.md or Cursor rules file so coding agents that help maintain your content apply the right terms: 
## Terminology

- Use "workspace" not "organization" or "team"—these are the same thing; workspace is correct
- Use "API key" not "token" or "secret" when referring to authentication credentials
- Use "publish" not "deploy" or "push" when describing sending changes live
This shapes every AI-assisted edit and prevents terminology drift as your documentation grows.

​
Write complete examples

When you include a code example, make it runnable. Agents surface examples to answer user questions, and coding agents like Claude Code or Cursor use them to generate code. An example with unexplained placeholder values, or that’s missing an import or initialization step, might produce errors when users try to use it. A complete example:
  • Can be run as-is, or includes clear placeholders that explain what to substitute
  • Includes all necessary imports and initialization
  • Shows the expected output or result where it isn’t obvious
If a full working example would be very long, break it up and make each section self-contained.

​
Avoid implicit references

Phrases like “the above,” “as mentioned,” “this value,” and “it” create ambiguity that humans resolve through context but AI assistants often can’t. Be explicit:
Implicit referenceExplicit reference
Pass this value to the next functionPass the session_token returned above to createSession()
As mentioned in the previous sectionAs explained in Authentication
It will return an errorThe API returns a 401 Unauthorized error
This precision also makes documentation easier for humans to read. They don’t have to hold information in their memory across pages to understand a sentence.
You’ve learned how to write content agents can use.Next up: Control what agents see — Configure what agents have access to, and give them the context they need.