Contribution Guide

How developers contribute documentation back to the Documentation repo alongside their code work.

Principle

Code and documentation travel together. Every significant decision, feature, or process change is documented in the single source of truth — this Documentation repo.

What to Document

Trigger	Document Type	Location	Template
Technology or architecture decision	ADR (Architecture Decision Record)	tech/decisions/	decision-record.md
New feature or module	Feature specification	solutions/{product}/	technical-spec.md
New integration or API	Technical spec	solutions/{product}/	technical-spec.md
Client-specific implementation	Client doc	clients/{client-slug}/	client-implementation.md
New operational procedure	Runbook	tech/runbooks/	runbook.md
Process change	Process document	company/processes/	process-document.md

Workflow

1. ADRs — Architecture Decision Records

Create an ADR before implementing any significant technical decision:

• Choosing a library or framework
• Changing database schema patterns
• Adding a new service or integration
• Modifying deployment architecture

Process:

1. Copy doc-templates/decision-record.md to tech/decisions/adr-NNN-short-title.md
2. Fill in Context, Decision, and Consequences
3. Set status to Proposed
4. Commit to the Documentation repo (or via the .docs/ submodule in your project)
5. After team review/approval, update status to Accepted

Numbering: Use sequential numbers. Check tech/decisions/ for the latest ADR number.

2. Feature Documentation

When building a new feature:

1. Write the spec before or during development, not after
2. Place it in the appropriate solutions/ subfolder
3. Include: purpose, data model changes, API endpoints, configuration, edge cases
4. Link related ADRs

3. Documenting via the Submodule

If your project includes the Documentation repo as a .docs/ submodule:

# Update submodule to latest
git submodule update --remote .docs

# Make documentation changes
cd .docs
git checkout -b docs/your-change-description
# ... edit files ...
git add . && git commit -m "docs: add ADR for caching strategy"
git push origin docs/your-change-description

# Create a PR in the Documentation repo
# Then update the submodule pin in your project
cd ..
git add .docs
git commit -m "docs: bump documentation submodule"

Alternatively, edit files directly in the Documentation repo and let the auto-sync GitHub Action bump the submodule in downstream projects.

4. Frontmatter Requirements

Every documentation file must include YAML frontmatter. See PROJECT_INSTRUCTIONS.md for the full specification. At minimum:

---
title: "Clear, descriptive title"
description: "One-line summary"
author: "Your Name"
created: YYYY-MM-DD
last-updated: YYYY-MM-DD
status: draft | active | archived
audience: technical | business | all
tags:
  - relevant-tag
owner: "Team or person responsible"
related-documents:
  - path/to/related-doc.md
---

5. Writing Standards

• Use British English spelling (organisation, behaviour, colour)
• Write in present tense, active voice
• Keep sentences under 25 words where possible
• Use tables for structured comparisons
• Include Mermaid diagrams for workflows and architecture

Review Process

1. All documentation changes go through PR review
2. At least one reviewer should verify technical accuracy
3. Frontmatter must be complete before merging
4. Links to related documents must be valid