Skip to content

Layered Readability Principle

Core Idea: Same documentation serves everyone—from CEO to intern engineer.

The Challenge

Documentation readers have vastly different needs:

Reader Wants Time Budget Technical Level
CEO Strategic overview 5 minutes Low
Investor Market + moat 30 minutes Medium
Auditor Security + compliance 2 hours High
CTO (external) Architecture 1 hour Very High
New Engineer How to contribute 2 hours High
Product Manager Features + roadmap 1 hour Medium

Problem: How do we serve all these needs without creating 6 different documentation sets?

Our Solution: Layered Architecture

Think of documentation like a pyramid:

┌─────────────────────────────────────────┐
│  Layer 1: Executive Summary (5-10 pages)│  ← CEO, Board
│  Vision, Market, Metrics                │
└─────────────────────────────────────────┘
           ↓
┌─────────────────────────────────────────┐
│  Layer 2: Strategic (20-30 pages)       │  ← Investors, Leadership
│  Business Model, Financials, Roadmap    │
└─────────────────────────────────────────┘
           ↓
┌─────────────────────────────────────────┐
│  Layer 3: Architecture (50-100 pages)   │  ← Auditors, CTOs
│  System Design, Security, AI/ML         │
└─────────────────────────────────────────┘
           ↓
┌─────────────────────────────────────────┐
│  Layer 4: Implementation (100+ pages)   │  ← Engineers, DevOps
│  API Docs, Service Specs, Runbooks      │
└─────────────────────────────────────────┘

Each layer:

  • ✅ Can stand alone
  • ✅ Links deeper for those who need more
  • ✅ Summarizes lower layers for those who don't

Layer 1: Executive Summary

Audience: CEO, Board Members, Busy Investors

Length: 5-10 pages

Purpose: "What is this product and why should I care?"

Content:

  • Product vision (2 paragraphs)
  • Market opportunity (1 chart)
  • Key differentiators (bullet points)
  • High-level architecture (1 diagram)
  • Traction metrics (4-5 numbers)
  • Team overview (names + titles)
  • 12-month roadmap (timeline)

Tone: Business-focused, minimal jargon

Example Entry Point:

# MachineAvatars: AI-Powered Conversational Avatars

MachineAvatars enables businesses to deploy lifelike 3D AI chatbots
that understand context, speak naturally, and scale infinitely.

**Market:** $X billion conversational AI market growing at Y% CAGR
**Traction:** 50+ customers, $500K ARR, 95% retention
**Ask:** Series A to accelerate growth

Exit Points:

  • Need technical details? → Layer 3 (Architecture)
  • Want business model? → Layer 2 (Strategic)
  • Just browsing? → Done, you got the gist

Layer 2: Strategic Documentation

Audience: Investors, Business Analysts, Product Leadership

Length: 20-30 pages

Purpose: "How does this business work and can it scale?"

Content:

  • Business Model - Revenue streams, pricing
  • Unit Economics - LTV, CAC, margins
  • Market Analysis - TAM/SAM/SOM, competition
  • Growth Strategy - Customer acquisition, expansion
  • Financial Projections - 3-year model
  • Product Roadmap - Quarterly features
  • Team & Hiring - Org chart, key hires
  • Risk Factors - What could go wrong?

Tone: Data-driven, strategic, explains "why"

Example Entry Point:

# Business Model

MachineAvatars uses a **SaaS subscription model** with three tiers:

| Tier         | Price/mo | Target Customer | ARR/Customer |
| ------------ | -------- | --------------- | ------------ |
| Starter      | $99      | SMBs            | $1,188       |
| Professional | $499     | Mid-market      | $5,988       |
| Enterprise   | Custom   | Large orgs      | $50K+        |

**Current MRR:** $42K (85% Pro tier)
**Average LTV:** $15K
**Average CAC:** $3K
**LTV:CAC Ratio:** 5:1 ✅

Exit Points:

  • Need technical architecture? → Layer 3
  • Want API details? → Layer 4
  • Enough for investment decision? → Done

Layer 3: Technical Architecture

Audience: Technical Auditors, External CTOs, Architects

Length: 50-100 pages

Purpose: "How is this actually built and is it sound?"

Content:

  • System Architecture - Components, interactions
  • AI/ML Architecture - Models, training, RAG
  • Data Architecture - Databases, storage, flows
  • Security Architecture - Auth, encryption, compliance
  • Infrastructure - Cloud, scaling, DR
  • Architecture Decision Records - Why we built it this way
  • Integration Points - Third-party services
  • Performance - Benchmarks, SLAs

Tone: Technical, diagram-heavy, evidence-based

Example Entry Point:

# System Architecture

MachineAvatars is built as a **microservices architecture**
with 20+ independent services:

```mermaid
graph TB
    Frontend[Next.js Frontend]
    Gateway[API Gateway :8000]
    Auth[Auth Service :8001]
    Chat3D[3D Chatbot :8011]
    LLM[LLM Service :8016]

    Frontend --> Gateway
    Gateway --> Auth
    Gateway --> Chat3D
    Chat3D --> LLM
```

Why microservices? See ADR-004

Databases:

  • MongoDB (Cosmos DB): User data, configurations
  • Milvus: Vector embeddings (10M+ vectors)
  • Azure Blob: Media storage

Traffic: 10K req/min peak, p95 latency < 200ms

**Exit Points:**
- Need service-level details? → Layer 4
- Want to see code? → GitHub repos
- Enough for architecture review? → Done

---

## Layer 4: Implementation Details

**Audience:** Engineers, DevOps, QA, New Hires

**Length:** 100+ pages (grows over time)

**Purpose:** "How do I work with/on this system?"

**Content:**
- **Service Documentation** - All 20+ services
- **API Reference** - Every endpoint, OpenAPI specs
- **Development Guides** - Setup, coding standards
- **Deployment Runbooks** - Step-by-step procedures
- **Troubleshooting** - Common issues, solutions
- **Testing** - Unit, integration, E2E strategies
- **Monitoring** - Dashboards, alerts, logs

**Tone:** Practical, code-heavy, copy-pasteable

**Example Entry Point:**
```markdown
# Auth Service

**Port:** 8001
**Purpose:** User authentication via JWT
**Owner:** Backend Team

## Quick Start

```bash
# Clone repo
git clone https://github.com/askgalore/machineagents-be

# Navigate to service
cd auth-service

# Install dependencies
pip install -r requirements.txt

# Run locally
uvicorn main:app --port 8001

API Endpoints

POST /login

Authenticates user and returns JWT.

Request:

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Errors:

  • 401 - Invalid credentials
  • 429 - Rate limit exceeded

Rate Limit: 5 req/min per IP

**Exit Points:**
- Need architecture context? → Layer 3
- Want business justification? → Layer 2
- Just need to use this API? → Done

---

## How Layers Connect

### Visual Navigation

Each layer has clear **entry points** and **exit points**:

**Homepage (`index.md`):**
```markdown
## Documentation Sections

### For Executives & Investors
- [Executive Summary](1-executive-summary/index.md) ← Layer 1
- [Business Documentation](2-business-documentation/index.md) ← Layer 2

### For Technical Auditors
- [System Architecture](3-product-architecture/index.md) ← Layer 3
- [AI/ML Architecture](4-ai-ml-architecture/index.md) ← Layer 3

### For Engineers & Developers
- [Technical Specification](6-technical-specification/index.md) ← Layer 4
- [API Documentation](6-technical-specification/api-documentation/index.md) ← Layer 4

Bidirectional Linking

Top-down (drill deeper):

# Executive Summary

...high-level overview...

**Want technical details?**
→ [System Architecture](../3-product-architecture/index.md)
→ [AI/ML Deep Dive](../4-ai-ml-architecture/index.md)

Bottom-up (context):

# Auth Service (Layer 4)

...detailed implementation...

**Why was JWT chosen over sessions?**
→ See [ADR-008: Authentication Strategy](../../13-architecture-decision-records/adr-008-auth.md) (Layer 3)

**Business impact:**
→ Enables stateless horizontal scaling ([Business Model](../../2-business-documentation/scalability.md)) (Layer 2)

Writing for Different Layers

Layer 1: Executive (Inspire)

❌ Bad:

Our system utilizes RESTful microservices with event-driven
architecture, deployedon Kubernetes with horizontal pod autoscaling
backed by ETCD for service discovery.

✅ Good:

MachineAvatars scales automatically to handle millions of conversations
simultaneously, ensuring your customers never wait.

Layer 2: Strategic (Convince)

❌ Bad:

We use MongoDB because it's web scale and has flexible schemas.

✅ Good:

Migration to Azure Cosmos DB reduced infrastructure costs by 40%
while improving uptime to 99.9%, directly impacting gross margin
from 62% to 71%.

Layer 3: Architecture (Explain)

❌ Bad:

We use Milvus because it's fast.

✅ Good:

Milvus was selected for vector storage after benchmarking against
Pinecone, Weaviate, and Postgres pgvector. Key factors:

- Performance: 15ms p95 latency vs. 450ms for pgvector
- Cost: Self-hosted saves $2K/month at 1M vectors
- Control: Custom indexing strategies for our use case

See [ADR-003](../13-architecture-decision-records/adr-003-milvus.md)
for full analysis.

Layer 4: Implementation (Instruct)

❌ Bad:

The auth service handles authentication.

✅ Good:

# Auth Service Quick Start

1. Set environment variables:
   ```bash
   export JWT_SECRET="your-secret-key"
   export TOKEN_EXPIRY=3600
  1. Run service:
uvicorn main:app --port 8001
  1. Test authentication: 
    curl -X POST http://localhost:8001/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"test123"}'

Expected response: Status 200 with JWT token.

---

## Common Patterns

### Summarize-Then-Expand

**Pattern:**
```markdown
## System Architecture

MachineAvatars uses a microservices architecture with 20+ services,
MongoDB for data storage, and Milvus for vector embeddings.

**[Read full architecture →](system-overview.md)** (10 min read)

### Quick Facts
- Services: 20+
- Databases: 2 (MongoDB + Milvus)
- Peak Traffic: 10K req/min
- Latency: <200ms p95

Progressive Disclosure

## Payment Processing

We integrate with **Razorpay** for payments.

<details>
<summary>Technical Implementation</summary>

Razorpay integration uses their Checkout.js library on the frontend
and webhooks for server-side validation...

[Full payment architecture →](payment-architecture.md)

</details>

Audience Callouts

> **For Executives:** This section explains our AI technology
> at a high level. [Skip to business impact →](#business-impact)

> **For Engineers:** Implementation details are in
> [AI Service Specs](../7-technical-specification/llm-service.md)

Benefits

For Readers

✅ Find what they need quickly - Start at their level
✅ Don't get overwhelmed - Only dive deeper if interested
✅ Understand context - Can always go up a layer

For Writers

✅ DRY (Don't Repeat Yourself) - Write once, link from multiple places
✅ Clear scope - Know which layer you're writing for
✅ Easier maintenance - Update in one place

For Organization

✅ Serves all stakeholders - One docs repo, many audiences
✅ Professional appearance - Investors see polish
✅ Efficient - No duplicate documentation efforts

Anti-Patterns to Avoid

❌ Flat Documentation

index.md (100 pages, everything mixed together)

Problem: Executives drown in technical details, engineers can't find anything.

❌ Duplicate Content

executive-summary.md → "Uses AI for conversations"
technical-docs.md → "Uses AI for conversations"

Problem: Maintenance nightmare, versions diverge.

Solution: Write once in appropriate layer, summary + link from others.

❌ Wrong Layer

# Executive Summary (Layer 1)

Our RAG system uses HNSW indexing in Milvus with cosine similarity..

Problem: Too technical for executives.

Fix: Move to Layer 3, summarize in Layer 1:

# Executive Summary

Our AI chatbots understand context by searching a knowledge base
of millions of documents in milliseconds.

**[Technical details →](3-product-architecture/rag-system.md)**

Success Metrics

Metric Target Measure
CEO can understand product 100% Survey after reading Layer 1
Engineers find answers fast < 2 min Time to find implementation details
Investors get full picture 90%+ confidence Post-due-diligence survey
No duplicate content 0% Automated similarity check

Last Updated: 2025-12-26
Version: 1.0
Owner: Documentation Lead

"One documentation, infinite perspectives."