Cashfree Documentation Content Guidelines - MSTP Style

Comprehensive guidelines for creating user-friendly developer documentation following MSTP standards

Cashfree Documentation Content Guidelines - MSTP Style

Overview

Your responsibility is to create user-friendly developer documentation that strictly adheres to the MSTP (Microsoft Style Guide for Technical Publications). These guidelines ensure consistent, clear, and professional documentation across all Cashfree API documentation while maintaining UK English standards and active voice throughout.

Style and Language Requirements

Core principles

• Use simple present tense and active voice consistently
• Write in UK English (spellings, terminology, and conventions)
• Refer to docs/styles/Microsoft path for MSTP guidance while maintaining UK English standards
• Apply Vale linting suggestions when suitable according to MSTP principles

Reference resources

• Follow MSTP guidelines from the docs/styles/Microsoft directory
• Use https://mintlify.com/docs/text for markdown syntax reference
• Apply UK English conventions throughout all documentation

Heading Structure

H1 headings

Use Title Case for all H1 headings (main page titles).

Example: # Payment Gateway Integration

H2, H3, H4+ headings

Use sentence case for all subheadings.

Example:

• ## Getting started with webhooks
• ### Configure webhook endpoints
• #### Set up authentication headers

Content Organization

Introductory statements

Always provide an introductory line before presenting lists, steps, or procedural content as required by MSTP style guide. This provides context and improves readability.

Avoid:

## Required parameters
- api_key
- order_id
- amount

Use:

## Required parameters
The following parameters are mandatory for all payment requests:
- api_key
- order_id
- amount

Procedural content

When writing step-by-step instructions, provide clear context before the steps.

Example:

## Set up your development environment
Complete these steps to configure your local environment for Cashfree integration:

1. Install the Cashfree SDK
2. Configure your API credentials
3. Test the connection

Language and Tone

Professional clarity

• Write in simple present tense and active voice consistently
• Use clear, direct language with UK English conventions
• Avoid unnecessary jargon
• Define technical terms when first introduced
• Apply Vale linting suggestions only when they align with MSTP principles

Consistency

• Use consistent terminology throughout documentation with UK English spellings
• Maintain the same naming conventions for parameters, methods, and endpoints
• Follow established patterns for similar content types
• Ensure simple present tense usage across all procedural content

Code Examples

Context and explanation

Provide context before code samples and explain what the code accomplishes using simple present tense.

Example:

## Create a payment order
The following request creates a new payment order. This example demonstrates the minimum required parameters:

```javascript
const orderData = {
  order_id: "order_001",
  order_amount: 100.00,
  order_currency: "INR"
};

### Code formatting
- Use appropriate language identifiers for syntax highlighting
- Include complete, runnable examples when possible
- Add inline comments for complex logic
- Follow Mintlify markdown syntax guidelines from https://mintlify.com/docs/text

## Content Structure Patterns

### API endpoint documentation
Structure API documentation consistently:

1. Brief description of the endpoint's purpose
2. HTTP method and URL
3. Authentication requirements
4. Request parameters (with introductory text)
5. Response format (with introductory text)
6. Code examples
7. Error handling information

### Integration guides
Follow this structure for integration guides:

1. Overview of what will be accomplished
2. Prerequisites (with introductory text)
3. Step-by-step implementation
4. Testing and validation
5. Troubleshooting common issues

## Response and Parameter Documentation

### Tables and lists
When documenting API parameters or responses, include descriptive introductory text.

**Example:**
```markdown
## Response fields
The API returns the following fields in a successful response:

| Field | Type | Description |
|-------|------|-------------|
| order_id | string | Unique identifier for the order |
| status | string | Current status of the payment |

Required vs optional

Clearly indicate which parameters are required and which are optional.

Error Handling

Error documentation structure

Document errors with clear explanations and solutions:

Example:

## Common errors
You may encounter these errors during integration:

**Invalid API key (401)**
This error occurs when the provided API key is incorrect or expired. Verify your API credentials in the Cashfree dashboard and ensure you use the correct environment keys.

Cross-References and Links

Internal linking

• Use descriptive link text that explains the destination
• Link to relevant sections within the same document or related documents
• Maintain link accuracy across documentation updates

External references

• Clearly indicate when linking to external resources
• Provide context for why the external link is relevant

Review Checklist

Before publishing documentation, verify:

• Content uses simple present tense and active voice throughout
• UK English spellings and conventions are applied consistently
• H1 headings use Title Case
• H2+ headings use sentence case
• Introductory text precedes all lists and procedures as per MSTP requirements
• Code examples include context and explanation
• Technical terms are defined on first use
• Content follows consistent structure patterns
• Links are accurate and descriptive
• Error messages include clear resolution steps
• Vale linting suggestions are applied only when suitable for MSTP compliance
• Mintlify markdown syntax guidelines are followed

Voice and Style

Audience consideration

Write for three primary audiences:

• Developers integrating APIs (primary)
• Technical decision-makers
• Non-technical stakeholders (occasional reference)

Instructional tone

• Be helpful and clear without being condescending
• Provide sufficient detail without overwhelming
• Use imperative voice for instructions (“Configure your settings” not “You should configure your settings”)
• Focus on what the user needs to accomplish
• Write in simple present tense and active voice consistently
• Use UK English conventions and spellings throughout

Formatting Standards

Code blocks

• Use language-specific syntax highlighting
• Keep code examples concise but complete
• Include necessary imports and dependencies

Emphasis

• Use bold for UI elements, field names, and important concepts
• Use code formatting for parameters, values, and short code snippets
• Use italics sparingly, primarily for emphasis or introducing new terms
• Follow Mintlify markdown syntax from https://mintlify.com/docs/text

Notes and warnings

Structure important information clearly:

Important: Always use HTTPS endpoints in production environments.

Note: Rate limits apply to all API endpoints. See the rate limiting section for details.