Skip to content
Home / Skills / Documentation / Project Documentation
DO

Project Documentation

Documentation core v1.0.0

Project Documentation

Overview

Project documentation encompasses all written artifacts that enable developers, operators, and stakeholders to understand, use, and maintain a software project. It includes READMEs, architecture decision records (ADRs), runbooks, onboarding guides, and contribution guidelines. In the full-lifecycle pipeline, @documentation-writer generates all project documentation in Phase 12 by synthesizing artifacts from all preceding phases.

Key Concepts

Documentation Hierarchy

┌──────────────────────────────────────────────────────┐
│              Documentation Structure                  │
├──────────────────────────────────────────────────────┤
│                                                       │
│  README.md              → First thing anyone reads    │
│  docs/                                                │
│  ├── getting-started.md → 5-minute quickstart         │
│  ├── architecture.md    → System design overview      │
│  ├── api-guide.md       → API usage with examples     │
│  ├── deployment.md      → Environment setup + deploy  │
│  ├── runbook.md         → Operational procedures      │
│  ├── troubleshooting.md → Common issues + fixes       │
│  └── adr/               → Architecture decisions      │
│      ├── 001-use-postgresql.md                        │
│      ├── 002-event-driven-arch.md                     │
│      └── template.md                                  │
│  CONTRIBUTING.md         → How to contribute          │
│  CHANGELOG.md            → Version history            │
└──────────────────────────────────────────────────────┘

README Template Sections

SectionPurposeRequired
Title + BadgesProject name, CI status, coverage, license✅
Overview1-2 sentence description✅
FeaturesKey capabilities list✅
Quick StartClone → install → run in 3 commands✅
ArchitectureHigh-level diagram + tech stack✅
API ReferenceLink to OpenAPI/AsyncAPI specsRecommended
ConfigurationEnvironment variables table✅
TestingHow to run tests✅
DeploymentDeploy instructions or linkRecommended
ContributingLink to CONTRIBUTING.md✅
LicenseLicense type✅

Architecture Decision Record (ADR) Format

# ADR-001: Use PostgreSQL as Primary Database

## Status
Accepted

## Context
We need a relational database that supports JSONB for flexible schema,
full-text search, and strong ACID compliance.

## Decision
Use PostgreSQL 16 with Flyway migrations.

## Consequences
- ✅ Strong ecosystem, JPA/Hibernate support
- ✅ JSONB, arrays, full-text search built-in
- ❌ Requires operational expertise for replication
- ❌ No auto-scaling (unlike DynamoDB)

## Alternatives Considered
| Option | Pros | Cons | Decision |
|--------|------|------|----------|
| PostgreSQL | Full-featured, JSONB | Operational overhead | ✅ Selected |
| MySQL | Widely known | Weaker JSONB support | ❌ |
| DynamoDB | Auto-scaling | No joins, vendor lock-in | ❌ |

Best Practices

  1. README is the front door — If it takes >2 minutes to understand the project, rewrite it
  2. Keep docs close to code — docs/ in the repo, not a separate wiki
  3. Use ADRs for decisions — Record why not just what was decided
  4. Include a runbook — Operators need incident procedures, not just developer docs
  5. Document environment variables — Table with name, description, default, required columns
  6. Update docs with code — PRs that change behavior must update relevant docs
  7. Write for the audience — Developers, operators, and stakeholders need different content
  8. Use diagrams — Architecture diagrams (Mermaid/PlantUML) convey more than paragraphs

Code Examples

✅ Good: README with All Sections

# 🛒 Order Management Service

![CI](https://github.com/org/order-service/actions/workflows/ci.yml/badge.svg)
![Coverage](https://img.shields.io/badge/coverage-87%25-green)
![License](https://img.shields.io/badge/license-MIT-blue)

Order lifecycle management for the e-commerce platform. Handles order
creation, payment processing, fulfillment tracking, and notifications.

## Quick Start

\```bash
git clone https://github.com/org/order-service.git
cd order-service
docker compose up -d
./mvnw spring-boot:run
# API available at http://localhost:8080/swagger-ui.html
\```

## Architecture

\```mermaid
graph LR
    A[React UI] --> B[API Gateway]
    B --> C[Order Service]
    C --> D[(PostgreSQL)]
    C --> E[Kafka]
    E --> F[Notification Service]
\```

## Configuration

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | PostgreSQL connection | `localhost:5432/orders` | Yes |
| `KAFKA_BROKERS` | Kafka bootstrap servers | `localhost:9092` | Yes |
| `LOG_LEVEL` | Application log level | `INFO` | No |

## Testing

\```bash
./mvnw test                    # Unit tests
./mvnw verify                  # Unit + Integration (requires Docker)
npm run test:e2e               # E2E tests (requires running app)
\```

❌ Bad: Minimal/Missing Documentation

# MyApp

A project.

## Setup
Run it.

Anti-Patterns

  1. No README — Repository with no documentation at all
  2. Stale docs — README says “Java 11” but project uses Java 21
  3. Wiki syndrome — Documentation in separate wiki nobody maintains
  4. Wall of text — No headings, no formatting, no code examples
  5. Missing quickstart — 10-page setup guide before you can run the app
  6. No ADRs — “Why did we choose X?” is unanswerable 6 months later

Testing Strategies

  • Doc link validation — CI job checks for broken links in markdown
  • README rendering — Preview all markdown renders correctly on GitHub
  • Doc freshness — Track last-modified dates; alert on stale docs (>6 months)
  • Onboarding test — New developer follows docs to set up; report friction points

References