torben
502971d147
Files changed: - .gitea/workflows/ci.yml - .wikitool-kb.json - AGENTS.md - CHANGES.md - INSTALL.md - README.md - VERSION - instructions/CONTRACT.md - instructions/dev/testing-conventions.md - instructions/german-terminology.md - instructions/kb-profiles.md - instructions/migrations/3.0.0-authoring-conventions.md - instructions/private-instance.md - instructions/setup-instance.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-manage/SKILL.md - kb/CONTRACT.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/comparisons/COLLECTION.md - kb/concepts/COLLECTION.md - kb/entities/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/new_page.py - tools/chemenu/conventions.py - tools/chemenu/kb_collections.py - tools/chemenu/kb_scan.py - tools/chemenu/provenance.py - tools/chemenu/sections.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_conventions.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_types_cmd.py - types/comparison.md - types/concept.md - types/entity.md - types/source.md - types/type-spec.md
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
---
|
|
profile: concepts
|
|
required_by_stack: false
|
|
---
|
|
|
|
# kb/concepts/ - Collection Contract
|
|
|
|
Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems,
|
|
and the decisions taken about them. A concept explains *how* or *why*, where an entity page
|
|
records *what*.
|
|
|
|
**Quality goal:** explanatory sufficiency - the page should answer *why it is done this way*
|
|
without the reader having to open the entity pages that use it. If the explanation only makes
|
|
sense once you already know the system, it is on the wrong page.
|
|
|
|
Inherits [kb/CONTRACT.md](../CONTRACT.md) for the rules the stack enforces - linking mechanics,
|
|
provenance, citation, the confidence machinery - and
|
|
[kb/CONVENTIONS.md](../CONVENTIONS.md) for what this instance decided: language, naming forms,
|
|
tone, relationship labels, the confidence rubric. Neither is restated here.
|
|
|
|
## Types offered
|
|
|
|
`concept` (`tools/wikitool types describe concept`).
|
|
|
|
## Decisions and ADRs
|
|
|
|
An architectural decision is a concept page, prefixed as
|
|
[kb/CONVENTIONS.md § Naming](../CONVENTIONS.md#naming) says. It records:
|
|
|
|
- **Context** - what forced a decision.
|
|
- **Decision** - what was chosen.
|
|
- **Consequences** - what this costs, not only what it buys.
|
|
- **Status** - proposed / accepted / deprecated / superseded.
|
|
- Links to every entity the decision affects.
|
|
|
|
A superseded ADR is never deleted or rewritten; a new one supersedes it and both link to the
|
|
other with `replaces` / `replaced by`.
|
|
|
|
## Outbound linking
|
|
|
|
A concept links to every entity that implements or uses it. A concept with no inbound entity
|
|
link is usually either premature or misfiled - `wikitool lint` reports it as an orphan.
|
|
|
|
Where two concepts compete, do not argue the comparison inside either page; create a page in
|
|
`kb/comparisons/` and link both to it.
|
|
|
|
## What does not belong here
|
|
|
|
- A concrete, pointable thing - that is an entity.
|
|
- A head-to-head evaluation of alternatives - that is a comparison.
|
|
- Generic textbook explanation with no connection to anything in this wiki. If no entity here
|
|
uses it, the page is not earning its keep.
|