torben
f350999053
Files changed: - AGENTS.md - CHANGES.md - VERSION - docs/language-boundaries.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/chemenu/commands/dist_cmd.py
106 lines
5.0 KiB
Plaintext
106 lines
5.0 KiB
Plaintext
---
|
|
# wikitool:template-unfilled - delete this line once the file is answered.
|
|
language: en
|
|
profile: none
|
|
sections:
|
|
links: Relationships
|
|
footnotes: Footnotes
|
|
---
|
|
|
|
# kb/ - Authoring Conventions of This Instance
|
|
|
|
The decisions [kb/CONTRACT.md](CONTRACT.md) deliberately does not make. The contract holds what
|
|
the code enforces and is identical in every instance; this file holds what *this* instance
|
|
chooses, and no other instance has to agree with a word of it.
|
|
|
|
**It binds all the same.** Everything below applies to every page under `kb/`, exactly as the
|
|
contract does. The difference is ownership, not authority: a rule here is changed by editing
|
|
this file, a rule there by changing the stack.
|
|
|
|
Ready-made answers to every section below - including a complete German profile - are in
|
|
[instructions/kb-profiles.md](../instructions/kb-profiles.md). That catalogue is a palette, not
|
|
an enum: adopt an entry, adapt it, or write your own. What is written *here* is what holds.
|
|
|
|
The frontmatter above is the one machine-read part. `sections:` names the headings the two
|
|
generated regions render under. Safe to change at any time - each region is located by its
|
|
marker pair, so a rename re-renders words and nothing else.
|
|
|
|
## Language
|
|
|
|
Pages are written in **{language}** - the `language:` in this file's own frontmatter, and the
|
|
one place that value is written down. This binds `kb/`, and inside the page type-specs
|
|
(`types/entity.md`, `types/concept.md`, `types/source.md`, `types/comparison.md`) exactly the
|
|
parts that become page text: each one's `## Template` block - the body skeleton every new page
|
|
starts from - and the `layout:` titles that head a catalog section. Their authoring guidance
|
|
around those is instruction to an agent, so it follows the control plane and stays English - the
|
|
same prose/identifier cut [kb/CONTRACT.md](CONTRACT.md#language-and-identifiers) makes inside a
|
|
page, applied one level up. Adopting this template into a non-English instance therefore means
|
|
translating those blocks, not the whole file. `raw/` is untouched
|
|
([raw/CONTRACT.md](../raw/CONTRACT.md)).
|
|
|
|
Two things follow from that value rather than being decided here, both stated once in
|
|
[AGENTS.md § File naming](../AGENTS.md#file-naming): the control plane stays English whatever an
|
|
instance writes its pages in, and an agent *speaks* the language named above.
|
|
|
|
The first of those is not a setting this file withholds - it is not a setting at all. `language:`
|
|
above is the only language value in the tree, and what it binds is page text; a control-plane
|
|
document is English even when this instance wrote it for itself and never ships it. Why that is
|
|
an architecture decision rather than an unset parameter:
|
|
[docs/language-boundaries.md](../docs/language-boundaries.md).
|
|
|
|
Which line is prose and which is an identifier - and therefore what is translated at all - is
|
|
the contract's rule, not this file's: see
|
|
[kb/CONTRACT.md § Language and identifiers](CONTRACT.md#language-and-identifiers).
|
|
|
|
{Which established foreign-language technical terms stay untranslated inside this instance's
|
|
prose, and where the vocabulary for that is looked up. Delete this paragraph if the KB language
|
|
is the one those terms are already in.}
|
|
|
|
### Section headings
|
|
|
|
The two generated regions render under the frontmatter's headings. An author never writes inside
|
|
them - they are rebuilt from frontmatter on every write. Any *other* heading is ordinary prose.
|
|
|
|
## Naming
|
|
|
|
- {Title form - words and spaces, or kebab-case, or the subject's own spelling.}
|
|
- {Singular or plural for entities.}
|
|
- {How a comparison page's title reads.}
|
|
- {The ADR prefix, if this instance files decisions as pages.}
|
|
- {What to name a thing: projects, systems, tools, technologies, people.}
|
|
|
|
The one naming fact that is *not* a choice, and therefore lives in the contract: the filename
|
|
stem is the page title, and `[[wikilinks]]` must match it exactly.
|
|
|
|
## Tone
|
|
|
|
{The register pages are written in, in one line.}
|
|
|
|
- {Words and constructions this instance refuses, with examples in the KB language.}
|
|
|
|
Good: {one sentence that is what this instance wants.}
|
|
|
|
Bad: {the same sentence written the way it must not be.}
|
|
|
|
## Relationship labels
|
|
|
|
**Not this file's to list, and not localized.** A label is a machine value in `related:`, drawn
|
|
from [instructions/link-taxonomy.md](../instructions/link-taxonomy.md) and authorised per
|
|
destination in each `kb/<name>/COLLECTION.md`'s `outbound:` block.
|
|
|
|
## Hedging
|
|
|
|
Hedge according to what the sources actually carry, not against a numeric score.
|
|
|
|
{How this instance signals general knowledge (`provenance: general`, no `sources:`) versus a
|
|
sourced claim, in the KB language.}
|
|
|
|
{How this instance's prose distinguishes a claim resting on a `normative`-standing source
|
|
(`raw/CONTRACT.md`'s `authority` axis) from one resting on `opinion`, and how it signals
|
|
disagreement between sources.}
|
|
|
|
## Keeping this file honest
|
|
|
|
Change it when a convention actually changes. `wikitool doctor` FAILs on a missing or unfilled
|
|
file, and `wikitool docs verify` refuses a `sections:` block that does not name both regions.
|