Documentation Standards

This guide outlines the standards for writing clear, comprehensive documentation for Formbricks.

Documentation Philosophy

User-Focused

Write for the reader, not yourself

Clear & Concise

Simple language, short sentences

Actionable

Provide clear steps and examples

Maintainable

Keep docs updated with code changes

MDX Format

Formbricks documentation uses MDX (Markdown + JSX) with Mintlify components.

File Structure

All documentation files must start with frontmatter:

---
title: Page Title
description: A clear, concise description of the page content
icon: iconName
---

Page content starts here...

Frontmatter Fields

title (required): Page title displayed in navigation and SEO
description (required): Short description for SEO and previews
icon (optional): Icon name from Lucide Icons

Heading Structure

Do NOT start with an H1 heading. The title in frontmatter becomes the H1.

Start with H2 (##) and maintain hierarchy:

---
title: Local Development Setup
---

## Prerequisites

Before you begin...

### Node.js Installation

Install Node.js version 20...

### Docker Setup

Install Docker...

## Installation Steps

### Clone Repository

Clone the repo...

Heading Case

Use Title Case for headings:

## Getting Started
## Local Development Setup
## Database Configuration

Mintlify Components

Cards

Use cards to organize links or features:

<CardGroup cols={2}>
  <Card title="Local Setup" icon="laptop-code" href="/development/local-setup">
    Set up Formbricks for local development
  </Card>
  <Card title="Architecture" icon="sitemap" href="/development/architecture">
    Understand the system architecture
  </Card>
</CardGroup>

Accordions

Use accordions for collapsible content:

<AccordionGroup>
  <Accordion title="Node.js Installation">
    Install Node.js version 20 or higher from [nodejs.org](https://nodejs.org)
  </Accordion>
  
  <Accordion title="Docker Setup">
    Download Docker from [docker.com](https://docker.com)
  </Accordion>
</AccordionGroup>

Steps

Use steps for sequential instructions:

<Steps>
  <Step title="Clone the Repository">
    ```bash
    git clone https://github.com/formbricks/formbricks.git
    cd formbricks
    ```
  </Step>
  
  <Step title="Install Dependencies">
    ```bash
    pnpm install
    ```
  </Step>
</Steps>

Callouts

Use callouts to highlight important information:

<Note>
This is a helpful note for users.
</Note>

<Tip>
Pro tip: Use this shortcut to save time!
</Tip>

<Warning>
Warning: This action cannot be undone.
</Warning>

<Info>
Additional context or background information.
</Info>

Code Blocks

Use fenced code blocks with language specification:

```typescript
const example = "code";
```

```bash
pnpm install
pnpm dev
```

```json
{
  "key": "value"
}
```

Code Groups

Show multiple code examples or comparisons:

<CodeGroup>
```typescript Good
const result = await fetchData();
```

```typescript Bad
const result = fetchData(); // Missing await!
```
</CodeGroup>

Tabs

Use tabs for different platforms or options:

<Tabs>
  <Tab title="npm">
    ```bash
    npm install formbricks
    ```
  </Tab>
  
  <Tab title="pnpm">
    ```bash
    pnpm install formbricks
    ```
  </Tab>
  
  <Tab title="yarn">
    ```bash
    yarn add formbricks
    ```
  </Tab>
</Tabs>

Writing Style

Voice and Tone

Active voice: “Install the dependencies” (not “Dependencies should be installed”)
Present tense: “The server starts” (not “The server will start”)
Second person: “You can configure” (not “One can configure”)
Conversational: Friendly but professional

Clarity

Run the following command to start the development server:

```bash
pnpm dev
```

The application will be available at http://localhost:3000.

Sentence Length

Keep sentences short and focused:

Ideal: 15-20 words per sentence
Maximum: 30 words
Break long sentences into multiple shorter ones

Lists

Use lists for related items:

The monorepo includes:

- `apps/web` - Main Next.js application
- `apps/storybook` - Component documentation
- `packages/database` - Prisma schema and migrations
- `packages/types` - Shared TypeScript types

Code Examples

Real Examples

Use real code from the codebase:

import { prisma } from "@formbricks/database";
import type { Survey } from "@formbricks/types/survey";

export const getSurvey = async (surveyId: string): Promise<Survey> => {
  return await prisma.survey.findUnique({
    where: { id: surveyId },
  });
};

Complete Examples

Provide complete, runnable examples:

// Complete example with imports and types
import { cache } from "react";
import { prisma } from "@formbricks/database";
import type { Survey } from "@formbricks/types/survey";

export const getSurvey = cache(async (surveyId: string): Promise<Survey | null> => {
  return await prisma.survey.findUnique({
    where: { id: surveyId },
  });
});

Explain Non-Obvious Code

Add comments to explain complex logic:

// Calculate cache TTL based on survey status
// Active surveys: 5 min, Draft: 1 hour, Completed: 24 hours
const ttl = survey.status === "active" ? 300 : 
            survey.status === "draft" ? 3600 : 86400;

Commands

Always Test Commands

Verify all commands work before documenting:

# Test each command
pnpm install
pnpm dev
pnpm build

Include Output (When Helpful)

Show expected output for clarity:

$ pnpm dev

> formbricks@0.0.0 dev
> turbo run dev --parallel

• Packages in scope: @formbricks/web, @formbricks/storybook
• Running dev in 2 packages

web:dev: ready - started server on 0.0.0.0:3000

Explain Flags and Options

# Build all packages with force flag (bypass cache)
pnpm build --force

# Run tests with coverage report
pnpm test:coverage

Links

Internal Links

Use relative paths for internal docs:

See [Local Setup](/development/local-setup) for installation instructions.
Check the [Code Style Guide](/development/standards/code-style).

External Links

Use full URLs for external resources:

Download [Node.js](https://nodejs.org) from the official website.
Refer to [Prisma documentation](https://prisma.io/docs) for details.

Link Text

Use descriptive link text:

Read the [contribution guidelines](/development/contributing) before submitting.
Install [Node.js version 20 or higher](https://nodejs.org).

Images

Image Guidelines

Use descriptive filenames: survey-editor-interface.png
Optimize images (compress, appropriate size)
Include alt text for accessibility
Store in /images directory

![Survey editor interface](/images/survey-editor.png)

Screenshots

For UI documentation:

Use consistent window size
Highlight relevant areas
Keep screenshots up-to-date
Include captions when needed

File Organization

Naming Conventions

Use kebab-case: local-setup.mdx, code-style.mdx
Be descriptive: database-migrations.mdx not db.mdx
Group related docs in folders:

development/
  overview.mdx
  local-setup.mdx
  architecture.mdx
  contributing.mdx
  standards/
    code-style.mdx
    testing.mdx
    documentation.mdx

Update docs.json when adding new pages:

{
  "group": "Development",
  "pages": [
    "development/overview",
    "development/local-setup",
    "development/architecture",
    "development/contributing",
    {
      "group": "Standards",
      "pages": [
        "development/standards/code-style",
        "development/standards/testing",
        "development/standards/documentation"
      ]
    }
  ]
}

Enterprise Features

Mark Enterprise-only features with a note:

## Advanced Analytics

<Info>
**Enterprise Feature**: This feature is only available with an Enterprise license.

Learn more about [Enterprise Edition](/self-hosting/enterprise).
</Info>

Advanced analytics provides...

API Documentation

Endpoint Documentation

## GET /api/v1/surveys/:surveyId

Retrieve a survey by ID.

### Parameters

- `surveyId` (string, required) - The survey ID

### Response

```json
{
  "data": {
    "id": "survey-1",
    "name": "Customer Satisfaction",
    "status": "active"
  }
}
```

### Error Responses

- `404` - Survey not found
- `403` - Unauthorized

Maintenance

Keep Docs Updated

When changing code:

Update related documentation
Test all commands/examples
Update screenshots if UI changed
Verify links still work

Review Checklist

Before submitting docs:

Common Mistakes

Starting with H1

Don’t start content with # heading. Use frontmatter title instead.

---
title: This is the H1
---

## Start with H2

Missing Frontmatter

Every MDX file must have frontmatter:

---
title: Required
description: Also required
icon: optional
---

Untested Commands

Always test commands before documenting:

# Test it first!
pnpm db:migrate:dev

Broken Links

Test all links:

Internal links: /development/local-setup
External links: https://nodejs.org

Resources

Mintlify Docs

Official Mintlify documentation

MDX Syntax

MDX syntax reference

Lucide Icons

Icon library reference

Code Style

Code style guidelines

Contributing

Standards

Documentation Index

​Documentation Philosophy

User-Focused

Clear & Concise

Actionable

Maintainable

​MDX Format

​File Structure

​Frontmatter Fields

​Heading Structure

​Heading Case

​Mintlify Components

​Cards

​Accordions

​Steps

​Callouts

​Code Blocks

​Code Groups

​Tabs

​Writing Style

​Voice and Tone

​Clarity

​Sentence Length

​Lists

​Code Examples

​Real Examples

​Complete Examples

​Explain Non-Obvious Code

​Commands

​Always Test Commands

​Include Output (When Helpful)

​Explain Flags and Options

​Links

​Internal Links

​External Links

​Link Text

​Images

​Image Guidelines

​Screenshots

​File Organization

​Naming Conventions

​Navigation

​Enterprise Features

​API Documentation

​Endpoint Documentation

​Maintenance

​Keep Docs Updated

​Review Checklist

​Common Mistakes

​Resources

Mintlify Docs

MDX Syntax

Lucide Icons

Code Style

Documentation Philosophy

MDX Format

File Structure

Frontmatter Fields

Heading Structure

Heading Case

Mintlify Components

Cards

Accordions

Steps

Callouts

Code Blocks

Code Groups

Tabs

Writing Style

Voice and Tone

Clarity

Sentence Length

Lists

Code Examples

Real Examples

Complete Examples

Explain Non-Obvious Code

Commands

Always Test Commands

Include Output (When Helpful)

Explain Flags and Options

Links

Internal Links

External Links

Link Text

Images

Image Guidelines

Screenshots

File Organization

Naming Conventions

Navigation

Enterprise Features

API Documentation

Endpoint Documentation

Maintenance

Keep Docs Updated

Review Checklist

Common Mistakes

Resources