---
type: types/type-guidance.md
name: comparison
description: When to write a comparison page instead of a neighboring type, and how to write a conforming one - structure and analysis rules that hold regardless of what this instance is comparing
---

# Comparison Guidance

`comparison` is the type for pages that set several entities, tools, technologies or approaches
systematically against one another along fixed criteria. Comparison pages support decisions and
make the trade-offs between alternatives visible.

## When to use

- Comparing several technologies or frameworks for a concrete purpose
- Analysing the advantages and disadvantages of different tools or libraries
- Evaluating alternative ways of solving a problem
- Documenting a decision process with several options examined

## When NOT to use

- For documenting a single entity or concept (use `entity` or `concept` respectively)
- For summaries of source material (use `source`)
- For pages covering a single subject rather than comparing several

## Authoring guidance

- A title that names the comparison (e.g. "Go vs Rust", "Kubernetes vs Docker Swarm"); it follows the established names of the subjects compared, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
- State clearly what is being compared and why
- Use a comparison table with the criteria as rows
- An analysis that evaluates the table rather than repeating it
- A recommendation wherever one can be justified

---

Relevant Notes:

- Comparison pages support technology selection and architecture decisions
- The entities compared should all exist as wiki pages
- The criteria should fit the decision at hand
- A comparison stays focused on one concrete purpose or decision context