From b01880e6694fa570b519cc54831cc6e714590812 Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Tue, 12 Aug 2025 08:56:58 +0000 Subject: [PATCH] Update MCP Docs with Mintlify guidelines This commit introduces a new documentation file, CLAUDE.md, outlining the standards and practices using Mintlify for our documentation. The update was needed to provide comprehensive guidelines for creating and maintaining consistent, high-quality documentation that supports user success while aligning with our project context. - Implement a framework for collaborative documentation efforts, encouraging constructive feedback and evidence-based reasoning. - Emphasize the importance of accuracy, usability, and making content evergreen. - Highlight writing standards such as using second-person voice, testing code examples, and maintaining consistent style and formatting. - Include a strict Git workflow, advocating for frequent commits and adherence to pre-commit hooks. The new CLAUDE.md file serves as a foundation for future documentation efforts, ensuring clarity and effectiveness in how we convey information to users. --- docs/CLAUDE.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/CLAUDE.md diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 0000000000..884844107e --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1,59 @@ +# Mintlify documentation + +Our docs are written using Mintlify. Please refer to the [Mintlify documentation](https://mintlify.com/docs/llms.txt) to write amazing Mintlify style docs, especially their components. Make sure to use their components where possible, especially for documenting parameters and responses using their ParamField, ResponseField, Expandable, etc. Use CodeGroup when you want to show multiple code editors side by side. Use Callout when you want to call out important information. Accordions are great for showing more detail but without the need to scroll. The Step component is great for showing a list of steps.There are also Tabs, Tooltips, etc. + +## Working relationship + +- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so +- ALWAYS ask for clarification rather than making assumptions +- NEVER lie, guess, or make up information + +## Project context + +- Format: MDX files with YAML frontmatter +- Config: docs.json for navigation, theme, settings +- Components: Mintlify components + +## Content strategy + +- Document just enough for user success - not too much, not too little +- Prioritize accuracy and usability of information +- Make content evergreen when possible +- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason +- Check existing patterns for consistency +- Start by making the smallest reasonable changes + +## docs.json + +- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation + +## Frontmatter requirements for pages + +- title: Clear, descriptive page title +- description: Concise summary for SEO/navigation + +## Writing standards + +- Second-person voice ("you") +- Prerequisites at start of procedural content +- Test all code examples before publishing +- Match style and formatting of existing pages +- Include both basic and advanced use cases +- Language tags on all code blocks +- Alt text on all images +- Relative paths for internal links + +## Git workflow + +- NEVER use --no-verify when committing +- Ask how to handle uncommitted changes before starting +- Create a new branch when no clear branch exists for changes +- Commit frequently throughout development +- NEVER skip or disable pre-commit hooks + +## Do not + +- Skip frontmatter on any MDX file +- Use absolute URLs for internal links +- Include untested code examples +- Make assumptions - always ask for clarification