> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adhdsimple.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Technical Documentation

> Minimal guide for creating technical documentation with flowcharts

<Warning>
  **KEEP THIS ULTRA SIMPLE**: This document is context for other AI agents. Do NOT add extra content, explanations, or "waffle". Only include the absolute minimum needed.
</Warning>

<Warning>
  **DOUBLE HEADING BUG**: MDX files automatically generate H1 from the title. Do NOT add a second H1 heading or you'll get duplicate headings in the rendered page.
</Warning>

## Writing Principles

### One Technical Concept Per Page

Each technical doc should focus on **one single technical concept** only. Never combine multiple technical concepts in a single 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

**Good**: "Authentication Flow"
**Bad**: "How Authentication Works" or "Understanding Authentication System"

**Good**: "Database Schema"
**Bad**: "How Database Schema Works" or "Understanding the Database Structure"

**Good Description**: "Authentication system architecture with flowchart"
**Bad Description**: "Comprehensive technical documentation explaining authentication"

## 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:

**For Simple Technical Pages:**

````mdx theme={null}
---
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]

\[Minimal technical explanation]

### \[Implementation Detail]

\[Minimal technical explanation]

````

**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]

<Note>
  **Only include notes for critical technical warnings**
</Note>

````

### 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

```mdx theme={null}
### [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

**Good**: `Auth[Supabase Auth] --> DB[(PostgreSQL)]`
**Bad**: `System[System] --> Data[Database]`

## 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`