torben
d49513bda6
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
1.7 KiB
1.7 KiB
type, name, description
| type | name | description |
|---|---|---|
| types/type-guidance.md | comparison | 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
entityorconceptrespectively) - 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