​

Mintlify technical writing rule

​

Core writing principles

​

Language and style requirements

• Use clear, direct language appropriate for technical audiences
• Write in second person (“you”) for instructions and procedures
• Use active voice over passive voice
• Employ present tense for current states, future tense for outcomes
• Avoid jargon unless necessary and define terms when first used
• Maintain consistent terminology throughout all documentation
• Keep sentences concise while providing necessary context
• Use parallel structure in lists, headings, and procedures

​

Content organization standards

• Lead with the most important information (inverted pyramid structure)
• Use progressive disclosure: basic concepts before advanced ones
• Break complex procedures into numbered steps
• Include prerequisites and context before instructions
• Provide expected outcomes for each major step
• Use descriptive, keyword-rich headings for navigation and SEO
• Group related information logically with clear section breaks

​

User-centered approach

• Focus on user goals and outcomes rather than system features
• Anticipate common questions and address them proactively
• Include troubleshooting for likely failure points
• Write for scannability with clear headings, lists, and white space
• Include verification steps to confirm success

​

Mintlify component reference

​

docs.json

• Refer to the docs.json schema when building the docs.json file and site navigation

​

Callout components

​

Note - Additional helpful information

​

Tip - Best practices and pro tips

​

Warning - Important cautions

​

Info - Neutral contextual information

​

Check - Success confirmations

​

Code components

​

Single code block

const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};

​

Code group with multiple languages

const response = await fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${apiKey}` }
});

​

Request/response examples

curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "john@example.com"}'

{
  "id": "user_123",
  "name": "John Doe", 
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}

​

Structural components

​

Steps for procedures

API_KEY=your_api_key_here

​

Tabs for alternative content

brew install node
npm install -g package-name

​

Accordions for collapsible content

const config = {
  performance: { cache: true, timeout: 30000 },
  security: { encryption: 'AES-256' }
};

​

Cards and columns for emphasizing information

​

API documentation components

​

Parameter fields

​

Response fields

​

Expandable nested fields

​

Media and advanced components

​

Frames for images

The analytics dashboard provides real-time insights

​

Videos

​

Tooltips

​

Updates

​

Required page structure

---
title: "Clear, specific, keyword-rich title"
description: "Concise description explaining page purpose and value"
---

​

Content quality standards

​

Code examples requirements

• Always include complete, runnable examples that users can copy and execute
• Show proper error handling and edge case management
• Use realistic data instead of placeholder values
• Include expected outputs and results for verification
• Test all code examples thoroughly before publishing
• Specify language and include filename when relevant
• Add explanatory comments for complex logic
• Never include real API keys or secrets in code examples

​

API documentation requirements

• Document all parameters including optional ones with clear descriptions
• Show both success and error response examples with realistic data
• Include rate limiting information with specific limits
• Provide authentication examples showing proper format
• Explain all HTTP status codes and error handling
• Cover complete request/response cycles

​

Accessibility requirements

• Include descriptive alt text for all images and diagrams
• Use specific, actionable link text instead of “click here”
• Ensure proper heading hierarchy starting with H2
• Provide keyboard navigation considerations
• Use sufficient color contrast in examples and visuals
• Structure content for easy scanning with headers and lists

​

Component selection logic

• Use Steps for procedures and sequential instructions
• Use Tabs for platform-specific content or alternative approaches
• Use CodeGroup when showing the same concept in multiple programming languages
• Use Accordions for progressive disclosure of information
• Use RequestExample/ResponseExample specifically for API endpoint documentation
• Use ParamField for API parameters, ResponseField for API responses
• Use Expandable for nested object properties or hierarchical information