Creating Technical Documentation

​

Writing Principles

​

One Technical Concept Per Page

​

Simple Technical Titles

• Title: Simple noun-focused titles - DO NOT include “How to” or “Understanding”
• Description: Use simple, clear language - avoid “comprehensive” or overly complex descriptions
• No Double Headings: Don’t add H1 (#) after the frontmatter title

​

Content Structure

• Always start with a flowchart or diagram
• Use clear subheadings to organize technical concepts
• Break down complex systems into simple components
• Keep explanations minimal and focused

​

Examples

​

Page Structure Rules

​

NEVER Include These Sections:

• Overview - If they’re on the page, they want the technical details
• Prerequisites - Only include critical technical requirements inline
• Introduction paragraphs - Keep opening content minimal
• Background - Jump straight to the technical content
• Opening sentences that repeat the title/description - No waffle at the top

​

ALWAYS Follow This Structure:

---
title: [Technical Concept]
description: '[Technical concept] architecture with flowchart'
---

## Architecture

```mermaid
[Flowchart here]

​

Components

​

[Component Name]

• Purpose: [Single sentence]
• Technology: [Stack/tools]
• Key Functions: [Bullet points]

​

[Component Name]

• Purpose: [Single sentence]
• Technology: [Stack/tools]
• Key Functions: [Bullet points]

​

Implementation

​

[Implementation Detail]

​

[Implementation Detail]

**For Complex Technical Pages:**
```mdx
---
title: [Technical Concept]
description: '[Technical concept] architecture with flowchart'
---

## Architecture

```mermaid
[Flowchart here]

​

[Technical Section Name]

​

[Component Name]

• Purpose: [Single sentence]
• Technology: [Stack/tools]
• Key Functions: [Bullet points]

​

[Technical Section Name]

​

[Component Name]

• Purpose: [Single sentence]
• Technology: [Stack/tools]
• Key Functions: [Bullet points]

### When to Use Section Headings:
- **Use section headings** only when you have multiple distinct technical areas
- **Skip section headings** for simple, single-concept technical docs
- **Don't add headings** just because you think you need them

### Section Heading Rules:
- **NO "Technical Overview"** - the description already says it's technical
- **NO "System Architecture"** or similar generic headings when you already have "Architecture"
- **Use specific technical names** like "Authentication Flow", "Database Operations", "API Integration"
- **Be specific** about what the section covers
- **Never repeat** words from the title or description

### Examples of Good Section Headings:
- "Authentication Flow"
- "Database Operations" 
- "API Integration"
- "Edge Functions"
- "Frontend Components"

### Examples of Bad Section Headings:
- "Technical Overview"
- "System Architecture" (when you already have "Architecture")
- "How It Works"
- "Implementation Details"

### NO WAFFLE RULE:
- **Start immediately** with the Architecture section and flowchart
- **Never repeat** what's already in the title or description
- **No opening sentences** like "This document explains..." or "The following describes..."
- **Jump straight to the flowchart** - the title and description already explain what the page covers

### Inline Notes Only
- Put notes INSIDE the relevant section
- Only note critical technical warnings
- Don't note obvious things (like "make sure the database is running")

## Essential Process

### 1. Create Flowchart First
```mermaid
graph TB
    A[Start] --> B[Define Components]
    B --> C[Map Connections]
    C --> D[Add Technical Details]
    D --> E[Document Implementation]

​

2. Document Structure

docs-development/
├── technical/[concept-name].mdx
├── architecture/[system-name].mdx

​

3. Required Sections

• Architecture: Always include Mermaid flowchart
• Components: List technical components with purpose/technology/functions
• Implementation: Minimal technical details only

​

4. Flowchart Rules

• Use Mermaid syntax
• Keep diagrams simple and focused
• Show flow, not details
• Use consistent node shapes
• Include external integrations

​

5. Component Documentation

### [Component Name]
- **Purpose**: [Single sentence explaining why it exists]
- **Technology**: [What it's built with]
- **Key Functions**: [What it does - bullet points]

​

Flowchart Guidelines

​

Node Types

• Rectangles: Internal components
• Diamonds: Decision points
• Cylinders: Databases
• Clouds: External services
• Circles: Start/end points

​

Flow Direction

• Top to Bottom: graph TB
• Left to Right: graph LR
• Choose based on what makes the flow clearest

​

Labeling

• Use clear, technical names
• Avoid generic terms like “System” or “Service”
• Be specific: “Supabase Auth”, “DHL API”, “PostgreSQL”

​

Examples

​

File Naming

• Use kebab-case: authentication-flow.mdx
• Be specific: database-schema.mdx not database.mdx
• Match the title concept: “Authentication Flow” = authentication-flow.mdx