Documentation Knowledge Base

Quick reference for technical documentation types, audiences, and best practices.

Documentation Types

By Purpose

Documentation Pyramid

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

Audience Analysis

Developer Personas

Content Mapping

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

Structure Principles

README Structure (Recommended)

# Project Name

Brief description (1-2 sentences)

## Badges
[Build][Coverage][Version][License]

## Features
- Feature 1
- Feature 2

## Installation
```bash
composer require ...

Quick Start

// minimal working example

Documentation

Links to detailed docs

Contributing

Link to CONTRIBUTING.md

License

MIT / Apache / etc.

### Architecture Doc Structure

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

Best Practices

Writing Principles

Code Examples Principles

✅ 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

Example Quality Checklist

// ✅ 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

Common Antipatterns

Documentation Smell Checklist

README Antipatterns

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

Architecture Doc Antipatterns

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

Documentation as Code

Principles

1. Version control — docs in git with code
2. Review — PRs include doc updates
3. Test — validate links, examples
4. Automate — generate where possible
5. CI/CD — build and deploy docs

File Organization

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

Markdown Best Practices

Formatting Guidelines

Code Block Languages

```php      # PHP code
```bash     # Shell commands
```yaml     # Configuration
```json     # API responses
```mermaid  # Diagrams
```sql      # Database

References

For detailed information, load these reference files:

• references/readme-patterns.md — README structure and examples
• references/api-documentation.md — API documentation guidelines
• references/architecture-docs.md — Architecture documentation patterns
• references/adr-format.md — ADR structure and examples
• references/diagramming.md — Diagram types and tools