chemenu/kb/CONVENTIONS.md

language, profile, sections

language	profile	sections
de	german	links footnotes Beziehungen Fußnoten

kb/ - Authoring Conventions of This Instance

The decisions kb/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 chose, 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.

Adopted from the german profile in instructions/kb-profiles.md. That catalogue is a palette, not an enum - what is written here is what holds, whether or not a profile says the same thing.

The frontmatter above is the one machine-read part. sections: names the headings the two generated regions render under - the links region wikitool xref owns and the footnotes region wikitool cite owns. Each sits between a marker pair, and the marker is what the tool locates it by, so the heading here is a display value: changing it re-renders the words above those regions and nothing else. Nothing matches on this text.

Contents

• Language
  • Section headings
• Naming
• Tone
• Relationship labels
• Hedging
• Keeping this file honest

Language

Pages are written in German - 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, 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 makes inside a page, applied one level up. raw/ is untouched (raw/CONTRACT.md).

Two things follow from that value rather than being decided here, both stated once in AGENTS.md § File naming: the control plane stays English whatever an instance writes its pages in, and an agent speaks the language named above.

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.

Established English technical terms stay English inside German prose - "GitOps", "Ownership Model", "Reverse Proxy", "Pull Request". Translate a term only where the German one is genuinely the more common usage. A coined German equivalent nobody else writes makes the page harder to find, not more idiomatic.

Which terms those are, which have a settled German form, and the register the prose is written in: instructions/german-terminology.md. It is lookup material, not a second rule - every entry in it is a decision that was made wrong once first.

Section headings

The two generated regions render under ## Beziehungen and ## Fußnoten. An author never writes inside them - they are rebuilt from frontmatter on every write, exactly like kb/index.md - and never has to write the heading either. Any other heading on a page is ordinary prose and is translated with the rest.

There is no ## Siehe auch region any more. It was the reciprocal half of a bidirectional xref add; under authored directional edges, see-also is a label inside the links region.

Naming

• Human-readable titles with spaces: Hybrid Search.md, Gitea Actions.md - not kebab-case.
• Singular for entities: HA Integration.md, not HA Integrations.md.
• Comparison pages read as a comparison: Go vs Rust.md.
• A decision (concept_type: decision) is named like any other concept - no adr-NNN- prefix. See kb/concepts/COLLECTION.md § Decisions.
• Prefer readability over convention when the two conflict.

What to name a thing: projects use their repository or common name; systems a descriptive name; tools the tool's own name; technologies their standard spelling and capitalization; people a full name or common handle.

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

Wikipedia style: factual, neutral, specific.

• No buzzwords ("bahnbrechend", "hochmodern", "leistungsstark", "revolutioniert").
• No AI filler ("es sei angemerkt", "es ist wichtig zu betonen", "in der heutigen Zeit").
• No em-dash asides carrying parenthetical reasoning.

Good: "MQTT ist ein leichtgewichtiges Publish-Subscribe-Protokoll für Geräte mit knappen Ressourcen."

Bad: "MQTT ist ein bahnbrechendes, hochmodernes Protokoll, das die IoT-Kommunikation revolutioniert - und es sei angemerkt, dass es ein Publish-Subscribe-Muster verwendet."

The blockquote cap is not here: wikitool lint reports it, so it is the contract's.

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 and authorised per destination in each kb/<name>/COLLECTION.md's outbound: block. - **depends-on:** [[Hermes]] is what a German page carries, and that is deliberate: the label is an identifier, so translating it would make the graph's semantics depend on the prose again.

Hedging

No number stands in for this any more (Gitea #60): hedge according to what the sources actually carry, not against a threshold.

• provenance: general with no sources: is general knowledge, and prose says so plainly - "im Allgemeinen", "üblicherweise" - rather than dressing it up as a sourced claim.
• A page citing an opinion-standing source does not speak in the tone of one citing a normative one (raw/CONTRACT.md's authority axis names the difference). Weigh the weakest source actually relied on for a given sentence, not the page's strongest citation.
• Where the sources disagree or only partly support a claim, say so in prose - "möglicherweise", "laut X, aber Y widerspricht" - instead of picking a side silently.

This is SOUL.md's existing standard ("Was nicht belegt ist, ist nicht gewusst, nur vermutet - und wird auch so benannt"), applied to kb/ without a number competing next to it.

Keeping this file honest

Change it when a convention actually changes. sections: is safe to change at any time - the regions are located by their markers and re-rendered under the new words on the next write. wikitool doctor FAILs on a missing or unfilled file, and wikitool docs verify refuses a sections: block that does not name both regions.