/\
       /  \
      / ADR \          ← Why (decisions)
     /________\
    /   Arch    \      ← How (structure)
   /______________\
  /    API Ref     \   ← What (details)
 /____________________\
/        README        \← Quick start

Evaluator → README (badges, features, comparison)
Beginner → Getting Started, Examples
Intermediate → API Reference, Guides
Expert → Architecture, Internals
Contributor → CONTRIBUTING, ADRs

# Project Name
 
Brief description (1-2 sentences)
 
## Badges
[Build][Coverage][Version][License]
 
## Features
-Feature 1
-Feature 2
 
## Installation

 
## Quick Start

 
## Documentation
Links to detailed docs
 
## Contributing
Link to CONTRIBUTING.md
 
## License
MIT / Apache / etc.

# Architecture
 
## Overview
High-level description
 
## System Context
C4 Context diagram
 
## Components
C4 Component diagram
 
## Data Flow
Sequence diagrams
 
## Technology Stack
| Layer | Technology |
|-------|------------|
 
## Decisions
Link to ADRs
 
## Deployment
Infrastructure diagram

✅ Good:
-Minimal complete example
-Copy-paste ready
-Shows expected output
-Uses realistic data
 
❌ Bad:
-Snippets that don't run
-Foo/Bar/Baz naming
-Missing imports
-Outdated syntax

// ✅ Good example
use App\Service\PaymentService;
 
$payment = new PaymentService($gateway);
$result = $payment->charge(
    amount: 99.99,
    currency: 'USD',
    customerId: 'cus_123'
);
 
echo $result->transactionId; // "txn_abc123"

// ❌ Bad example
$foo = new Foo();
$bar = $foo->doSomething($baz);
// returns something

❌ No installation instructions
❌ No usage examples
❌ Badges only (no content)
❌ Generated API docs only
❌ Outdated screenshots
❌ Broken links
❌ No clear project description

❌ Box-and-arrow without explanation
❌ Outdated diagrams
❌ Missing "why" context
❌ No technology justification
❌ Inconsistent terminology
❌ Too much detail (implementation in arch doc)

project/
├── README.md           # Quick start
├── docs/
│   ├── architecture/
│   │   ├── README.md
│   │   ├── diagrams/
│   │   └── decisions/ (ADRs)
│   ├── api/
│   │   └── README.md
│   ├── guides/
│   │   ├── getting-started.md
│   │   └── deployment.md
│   └── reference/
│       └── configuration.md
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE