Documentation Knowledge Base

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

Documentation Types

By Purpose

| Type | Audience | Goal | Examples | |------|----------|------|----------| | README | New users | Quick start | badges, install, basic usage | | Architecture | Developers | System understanding | layers, components, decisions | | API | Integrators | Integration | endpoints, params, responses | | ADR | Team | Decision history | context, decision, consequences | | Getting Started | Beginners | First success | step-by-step tutorial | | Reference | All | Quick lookup | methods, options, configs | | Troubleshooting | Users | Problem solving | FAQ, error messages, solutions | | CHANGELOG | All | Version history | features, fixes, breaking |

Documentation Pyramid

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

Audience Analysis

Developer Personas

| Persona | Needs | Tone | |---------|-------|------| | Evaluator | Quick value assessment | Benefits, features | | Beginner | Step-by-step guidance | Simple, encouraging | | Intermediate | Best practices, patterns | Technical, practical | | Expert | Advanced configs, internals | Concise, complete | | Contributor | Setup, conventions | Technical, detailed |

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

| Principle | Description | Example | |-----------|-------------|---------| | Scannable | Headers, bullets, tables | Use ## for sections | | Task-oriented | Focus on goals, not features | "How to X" not "X feature" | | Example-driven | Code before explanation | php example then text | | Layered | Quick start → details | README → Guide → Reference | | Up-to-date | Doc near code | Update together |

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

| Smell | Detection | Fix | |-------|-----------|-----| | Stale | Code changed, docs not | Review on PR | | Wall of text | No headers, no examples | Structure + code | | Jargon soup | Undefined terms | Glossary, links | | Dead links | 404 errors | Link checker CI | | No examples | Pure prose | Add code blocks | | Copy-paste broken | Missing imports | Run examples | | Version mismatch | Wrong versions | Automate sync |

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

| Element | Usage | |---------|-------| | # H1 | Document title only | | ## H2 | Main sections | | ### H3 | Subsections | | - | Unordered lists | | 1. | Ordered steps | | > | Warnings, notes | | \``| Code blocks | ||` | Data tables |

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