types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
Files changed: - AGENTS.md - CHANGES.md - VERSION - docs/ownership-and-templates.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/types_cmd.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_dist_upgrade.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/type_resolver.py - tools/chemenu/types_core.py - types/comparison.guidance.md - types/comparison.md - types/concept.guidance.md - types/concept.md - types/entity.guidance.md - types/entity.md - types/source.guidance.md - types/source.md - types/type-guidance.md - types/type-guidance.schema.yaml - types/type-spec.md
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user