Skip to content

Commit b01880e

Browse files
committed
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.
1 parent e9cc7de commit b01880e

File tree

1 file changed

+59
-0
lines changed

1 file changed

+59
-0
lines changed

docs/CLAUDE.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Mintlify documentation
2+
3+
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.
4+
5+
## Working relationship
6+
7+
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
8+
- ALWAYS ask for clarification rather than making assumptions
9+
- NEVER lie, guess, or make up information
10+
11+
## Project context
12+
13+
- Format: MDX files with YAML frontmatter
14+
- Config: docs.json for navigation, theme, settings
15+
- Components: Mintlify components
16+
17+
## Content strategy
18+
19+
- Document just enough for user success - not too much, not too little
20+
- Prioritize accuracy and usability of information
21+
- Make content evergreen when possible
22+
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
23+
- Check existing patterns for consistency
24+
- Start by making the smallest reasonable changes
25+
26+
## docs.json
27+
28+
- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
29+
30+
## Frontmatter requirements for pages
31+
32+
- title: Clear, descriptive page title
33+
- description: Concise summary for SEO/navigation
34+
35+
## Writing standards
36+
37+
- Second-person voice ("you")
38+
- Prerequisites at start of procedural content
39+
- Test all code examples before publishing
40+
- Match style and formatting of existing pages
41+
- Include both basic and advanced use cases
42+
- Language tags on all code blocks
43+
- Alt text on all images
44+
- Relative paths for internal links
45+
46+
## Git workflow
47+
48+
- NEVER use --no-verify when committing
49+
- Ask how to handle uncommitted changes before starting
50+
- Create a new branch when no clear branch exists for changes
51+
- Commit frequently throughout development
52+
- NEVER skip or disable pre-commit hooks
53+
54+
## Do not
55+
56+
- Skip frontmatter on any MDX file
57+
- Use absolute URLs for internal links
58+
- Include untested code examples
59+
- Make assumptions - always ask for clarification

0 commit comments

Comments
 (0)