​
Overview

At Formbricks, we maintain strict documentation standards to ensure code clarity, maintainability, and ease of use for both internal developers and external contributors.

​
Contribute to Documentation

We use Mintlify to maintain our documentation. You can find more information about how to contribute to the documentation in the README file.

​
Code Documentation

​
Function Documentation

  1. Complex Logic Documentation
    • All functions with complex logic must include JSDoc comments
    • Document parameters, return types, and potential side effects
    • Example:
/**
Creates a new user and initializes their preferences
@param {string} name - User's full name
@param {UserOptions} options - Configuration options for user creation
@returns {Promise<User>} The created user object
@throws {ValidationError} If name is invalid
*/
async function createUser(name: string, options: UserOptions): Promise<User> {
  // implementation
}
  1. TypeScript Ignore Comments
    • When using @ts-ignore or @ts-expect-error, always include a comment explaining why
    • Example:
// @ts-expect-error -- Required for dynamic function calls
void window.formbricks.setup(...args);

​
API Documentation

  1. API Endpoints
    • All new API endpoints must be documented in the OpenAPI specification
    • Include request/response schemas, authentication requirements, and examples
    • Document both Client API and Management API endpoints
    • Place API documentation in the docs/api-reference directory
  2. Authentication
    • Clearly specify authentication requirements
    • Document API key usage and permissions
    • Include error scenarios and handling

​
Feature Documentation

  • All new features must include a feature documentation file
  • Document the feature’s purpose, usage, and implementation details
  • Include code examples and best practices

​
Working with Mintlify

We use Mintlify to write our documentation.

​
File Structure

  1. MDX Files
    • All documentation files must use the .mdx extension
    • Include frontmatter with required metadata:
---
title: "Document Title"
description: "Brief description of the content"
icon: "appropriate-icon"
---
  1. Navigation
    • Add new pages to the appropriate section in docs/mint.json
    • Follow the existing navigation structure
    • Include proper redirects if URLs change

​
Content Guidelines

  1. Writing Style
    • Use clear, concise language
    • Break content into logical sections with proper headings
    • Include practical examples and code snippets
    • Use Mintlify components for notes, warnings, and callouts:
<Note>
Important information goes here
</Note>
  1. Media and Assets
    • Store images in the appropriate /images subdirectory
    • Use descriptive alt text for all images
    • Optimize images for web delivery
    • Use relative paths for internal links
  2. Code Examples
    • Specify the language for all code blocks
    • Include comments for complex code snippets
    • Use proper indentation and formatting

​
Validation

  1. Local Testing
    • Test documentation locally using Mintlify CLI:
mintlify dev
  1. Review Process
    • Documentation changes require peer review
    • Verify all links and references work
    • Ensure proper formatting and rendering
These documentation requirements ensure that our codebase remains maintainable, accessible, and well-documented for both current and future developers.