LogicSpike Documentation Standards

Last Updated: 2026-03-24 Status: Active — Enforced for all new docs

This guide defines the writing standards, structure rules, and visual quality expectations for all markdown documentation in docs/. Every new or updated doc must follow these rules to ensure consistency across the LogicSpike docs application.

1. File Organization

1.1 Folder Structure

Every doc must live in the correct category folder:

1.2 File Naming

• Use kebab-case: auth-login-flow.md, NOT authLoginFlow.md
• Use descriptive names: razorpay-setup-guide.md, NOT setup.md
• Suffix with doc type when helpful: *-vision.md, *-spec.md, *-journey.md, *-guide.md

2. Document Header (Required)

Every document must start with this structure:

# Document Title
 
> **Last Updated:** YYYY-MM-DD
> **Status:** Active | Draft | Deprecated

Status Values

3. Content Structure

3.1 Heading Hierarchy

• H1 (#): Document title — exactly ONE per file
• H2 (##): Major sections — numbered (## 1. Overview, ## 2. Architecture)
• H3 (###): Subsections
• H4 (####): Detail items (API endpoints, config options)

3.2 Required Sections by Doc Type

Vision Docs (*-vision.md):

1. Purpose (The Why)
2. Target Audience
3. Core Features / Value Props
4. Architecture Overview (with diagram)
5. Implementation Phases

API Specs (*-spec.md):

1. Service Owner
2. Base URL
3. Endpoints (grouped by domain)
4. Error Codes table
5. Auth requirements per endpoint

User Journeys (*-journey.md):

1. Persona description
2. Step-by-step flow (with sequence diagram)
3. Edge cases / error paths
4. Backend operations per step

Architecture Decision Records (adr-*.md):

1. Context / Problem
2. Options Considered (comparison table)
3. Decision
4. Consequences / Trade-offs

Guides (*-guide.md):

1. Prerequisites
2. Step-by-step instructions
3. Code examples
4. Verification / testing steps

4. Diagrams (Critical)

4.1 Always Use Mermaid

All architecture diagrams, flows, and sequences must use mermaid code blocks. Never use ASCII art for new diagrams.

```mermaid
flowchart TD
    A["Node A"] --> B["Node B"]
```

4.2 Mermaid Style Rules

Every mermaid diagram must include explicit style declarations for colorful, professional output:

Color Palette (use consistently across all docs):

Example — Properly styled flowchart:

```mermaid
flowchart TD
    Client["🖥️ Client App"]
    Gateway["🛡️ API Gateway"]
    Service["⚙️ Backend Service"]
    DB[("🐘 Database")]
 
    Client --> Gateway --> Service --> DB
 
    style Client fill:#475569,stroke:#94a3b8,stroke-width:2px,color:#fff
    style Gateway fill:#2563eb,stroke:#60a5fa,stroke-width:2px,color:#fff
    style Service fill:#7c3aed,stroke:#a78bfa,stroke-width:2px,color:#fff
    style DB fill:#0d9488,stroke:#2dd4bf,stroke-width:2px,color:#fff
```

4.3 Subgraph Styling

Subgraphs (grouped sections) use dark backgrounds:

style SubgraphName fill:#0f172a,stroke:#334155,stroke-width:2px,color:#e2e8f0

4.4 Sequence Diagrams

Use rect blocks with semi-transparent colors to group phases:

```mermaid
sequenceDiagram
    rect rgba(59, 130, 246, 0.08)
        Note over A,B: Phase 1 — Authentication
        A->>B: Login request
    end
 
    rect rgba(139, 92, 246, 0.08)
        Note over A,B: Phase 2 — Data Fetch
        A->>B: GET /data
    end
```

4.5 Edge / Link Styling

Use linkStyle for colored connections:

linkStyle 0,1,2 stroke:#3b82f6,stroke-width:3px
linkStyle 3,4 stroke:#a78bfa,stroke-width:2px,stroke-dasharray:5

• Solid thick (stroke-width:3px): Direct service bindings
• Dashed (stroke-dasharray:5): Event-driven / async communication

5. Code Blocks

5.1 Always Specify Language

Every code block must have a language tag for syntax highlighting:

```json
{ "key": "value" }
```
 
```typescript
const x: string = "hello";
```
 
```sql
SELECT * FROM users WHERE tenant_id = 'tnt_123';
```

Never use bare ``` without a language. Use plaintext if no language applies.

5.2 Keep Code Blocks Focused

• Max 20 lines per code block. Split longer examples.
• Show only the relevant part — don't dump entire files.
• Add comments for non-obvious lines.

6. Tables

Use tables for any comparison, listing, or structured data:

| Column A | Column B | Column C |
|:---|:---|:---|
| Value 1 | Value 2 | Value 3 |

Rules:

• Always left-align (:---)
• Use header row with bold intent (column names should be self-explanatory)
• Prefer tables over bullet lists when data has 2+ attributes

7. Callout Blocks

Use GitHub-style callout syntax for important notes:

> [!NOTE]
> Helpful context or background information.
 
> [!IMPORTANT]
> Critical requirement that must be followed.
 
> [!WARNING]
> Potential pitfall or dangerous action.

For status/metadata headers at the top of docs, use blockquotes:

> **Last Updated:** 2026-03-24
> **Status:** Active
> **Service:** `apps/manager`

8. Cross-References

Link to other docs using relative markdown paths:

See [System Architecture](../architecture/system-architecture.md) for the full service map.

Rules:

• Always use relative paths from the current file
• Link text should be the document title, not "click here"
• Reference specific sections with anchors when possible

9. Writing Style

1. Be direct — Lead with the answer, not the context
2. Use active voice — "The Gateway verifies the JWT" not "The JWT is verified by the Gateway"
3. Define acronyms on first use — "PBAC (Permission-Based Access Control)"
4. No filler — Cut "basically", "essentially", "in order to", "it should be noted that"
5. Present tense — "The service returns a 200" not "The service will return a 200"
6. Technical precision — Use exact names (x-tenant-id, not "the tenant header")

10. Quality Checklist

Before merging any doc, verify:

• H1 title + metadata header (Last Updated, Status)
• Numbered H2 sections
• At least one mermaid diagram for architecture/flow docs
• All diagrams have explicit style declarations with the standard color palette
• All code blocks have language tags
• Tables used for structured data (not nested bullets)
• Cross-references use relative links
• No orphan docs — linked from at least one other doc
• File is in the correct category folder
• File uses kebab-case naming