Documentation

This document documents how we document things. Funny, right?

Documentation Guidelines

Documentation should assume general familiarity with the basic concepts of the Matrix specification. Wherever possible, especially at functions implementing an endpoint of the Matrix specification, a link should be made to the relevant section. The primary purpose of the documentation in Arminius is to document our implementation and choices made when implementing the specification, not documenting the Matrix protocol.

Running Locally

Using Nix

If you have Nix installed, you can render the docs using:

  nix build .#docs
  firefox ./result/index.html

Without Nix

First, install the required crates: cargo install mdbook mdbook-mermaid

Initialize mdbook-mermaid using: mdbook-mermaid install docs/

Build the database documentation (requires a running psql database with applied migrations): ./docs/document_tables/document_tables.sh

And open them in your browser (automatically reloading on change): mdbook serve --open docs/

Formatting

Markdown files are formatted automatically via nix fmt using mdformat and the mdformat-footnote plugin. For repository formatting configuration and exclusions, see Formatting and Linting.

Visual Documentation: Diagrams and Admonitions

This section covers how to enhance your documentation with visual diagrams using Mermaid and highlighted callouts using admonitions.

Mermaid Diagrams

Mermaid is a powerful diagramming and charting tool that renders Markdown-inspired text definitions to create diagrams dynamically. It’s perfect for technical documentation because diagrams are defined as code, making them version-controllable and easy to maintain.

Use Mermaid when you need to:

• Visualize system architecture or data flow
• Document processes, workflows, or decision trees
• Show relationships between components
• Illustrate sequence interactions between services
• Create organizational charts or hierarchies
• Document database schemas or entity relationships

Don’t use Mermaid when:

• You need highly detailed technical drawings
• Custom styling is critical to the diagram’s purpose

Supported Diagram Types

Flowcharts

Perfect for processes, decision flows, and system overviews.

```mermaid
flowchart TD
    A[Start] --> B{Is user logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login form]
    D --> E[Authenticate]
    E --> F{Valid credentials?}
    F -->|Yes| C
    F -->|No| G[Show error message]
    G --> D
```

flowchart TD
    A[Start] --> B{Is user logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login form]
    D --> E[Authenticate]
    E --> F{Valid credentials?}
    F -->|Yes| C
    F -->|No| G[Show error message]
    G --> D

When to use: Process documentation, user flows, system logic, troubleshooting guides.

Sequence Diagrams

Ideal for showing interactions between different actors or systems over time.

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Submit form
    Frontend->>API: POST /api/users
    API->>Database: INSERT user data
    Database-->>API: Success response
    API-->>Frontend: 201 Created
    Frontend-->>User: Show success message
```

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Submit form
    Frontend->>API: POST /api/users
    API->>Database: INSERT user data
    Database-->>API: Success response
    API-->>Frontend: 201 Created
    Frontend-->>User: Show success message

When to use: API documentation, microservice interactions, authentication flows, integration guides.

Entity Relationship Diagrams

Perfect for database design and data modeling.

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "ordered in"

    CUSTOMER {
        int id PK
        string name
        string email
        date created_at
    }

    ORDER {
        int id PK
        int customer_id FK
        date order_date
        decimal total
    }
```

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "ordered in"

    CUSTOMER {
        int id PK
        string name
        string email
        date created_at
    }

    ORDER {
        int id PK
        int customer_id FK
        date order_date
        decimal total
    }

When to use: Database documentation, data architecture guides, schema migration documentation.

Best Practices for Mermaid

1. Keep diagrams focused: Each diagram should illustrate one concept or process
2. Use descriptive labels: Make node and edge labels clear and meaningful
3. Maintain consistent styling: Use similar formatting across diagrams in your documentation
4. Test rendering: Always verify your diagrams render correctly in your documentation system
5. Version control: Since Mermaid diagrams are text, they can be easily tracked in version control
6. Add context: Always accompany diagrams with explanatory text

Syntax Tips

• Use meaningful IDs for nodes: user_login[User Login] instead of A[User Login]
• Leverage subgraphs for grouping related components
• Keep line lengths reasonable for better readability in source code

Admonitions

Admonitions are highlighted callout boxes that draw attention to important information. They help break up dense text and guide readers to critical details.

Documentation can be found in the mdbook documentation.