chemenu/kb/CONVENTIONS.md

language, profile, sections

language	profile	sections
de	german	relationships see_also footnotes Beziehungen Siehe auch 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 three headings wikitool xref and wikitool cite write into; tools/chemenu/conventions.py reads them and tools/chemenu/sections.py is what the rest of the compiler asks. Renaming one here changes what the tool writes; what it still recognizes is the union of that name, any section_aliases: declared beside it, and the names this stack wrote before this file existed. That asymmetry is the translation path: a page keeps working under its old heading until it is itself translated.

Language

Pages are written in German. This binds kb/ and the authoring surface that shapes it - the page type-specs types/entity.md, types/concept.md, types/source.md and types/comparison.md. raw/ is untouched (raw/CONTRACT.md), and the control plane stays English: AGENTS.md, the stage contracts, this file, instructions/, and the type-specs for non-page artifacts.

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 canonical names are the frontmatter's: ## Beziehungen, ## Siehe auch, ## Fußnoten. The English forms this stack wrote before the corpus was translated are still recognized, so a page carrying ## Relationships is found and appended to correctly and cite sync leaves an untranslated ## Footnotes alone. Renaming such a heading is the translation pass's job, never a side effect of another command. Any other heading an author adds is ordinary prose and is translated with the rest.

Naming

• Human-readable titles with spaces: Hybrid Search.md, Gitea Actions.md - not kebab-case.
• Singular for entities: ha-core.md, not ha-cores.md.
• Comparison pages read as a comparison: Go vs Rust.md.
• ADRs are prefixed: adr-001-use-go-modules.md.
• 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

tools/wikitool xref add --rel-a/--rel-b takes a free-text label. This instance uses a typed one rather than a generic one:

hängt ab von · verwendet · implementiert · erweitert · ersetzt · steht in Konflikt mit · benötigt · erzeugt · konsumiert · besitzt · pflegt · läuft auf · verwandt mit (last resort)

The labels are prose written into a - **label:** [[Title]] bullet; no code matches on them, so an untranslated page's English label is stale wording, not a broken reference.

Confidence rubric

confidence_base is set by hand and confidence is derived from it - that mechanism is the contract's. What the number means is this instance's:

Base score for a single source is 0.5, adjusted by:

• +0.2 per supporting source (max +0.6)
• +0.2 if confirmed <30 days ago, +0.1 if <90 days
• +0.1 for official documentation, +0.05 for a reputable secondary source
• +0.1 if multiple independent sources agree

In prose, hedge according to the score: below 0.6 write "möglicherweise"/"kann"; below 0.4 write "unsicher"/"unbestätigt".

Keeping this file honest

Change it when a convention actually changes, and treat a change to sections: as a corpus migration rather than an edit: existing pages keep their old headings until something translates them, and the alias list is what carries them in the meantime. wikitool doctor FAILs on a missing or unfilled file, and wikitool docs verify refuses a sections: block that does not name all three slots.