---
type: types/type-spec.md
name: comparison
description: Structured type for comparison pages that set several entities or approaches against one another
schema: types/comparison.schema.yaml
base_dir: comparisons
page_ref_fields: [entities, related]
---

# Comparison

`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

## Frontmatter

| Field | Required | Use |
|---|---:|---|
| `type` | Yes | `types/comparison.md` |
| `tags` | No | Navigation tags for categorization |
| `created` | Yes | Creation date (YYYY-MM-DD) |
| `entities` | Yes | Titles of the entities compared |
| `related` | No | Declared outbound edges - one `compares-with` edge per subject, written by `wikitool xref add` |
| `summary` | Yes | One-liner for `kb/index.md` |

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

## Template

The block below is page material, so it is written in this instance's KB language
(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
become the headings of every page `wikitool new comparison` scaffolds.

```markdown
# Comparison: {name}

## Überblick

TODO: Kurzer Überblick, was verglichen wird und warum der Vergleich zählt.

## Vergleichstabelle

| Kriterium | {entities|table_header} |
|-----------|{entities|table_sep}|
| TODO | {entities|table_cells} |

## Analyse

TODO: Auswertung des Vergleichs. Welche Muster zeigen sich? Was sind die entscheidenden Unterschiede?

## Empfehlung

TODO: Falls möglich - was wann und für wen zu verwenden ist. Unter welchen Umständen ist welche Option die beste?
```

`# Comparison:` stays as a prefix - unlike `source` it is no `title_prefix` but a pure template
convention, and the page title itself (`Go vs Rust`) does not carry it. When `wikitool xref` adds
a relationship, the tool-managed cross-reference section appears; what it is called is the
instance's decision in `kb/CONVENTIONS.md` (`sections:`).

---

Additional 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