Documentation

​

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
}

2. 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"
---

2. 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>

2. 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

3. 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

2. 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.