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
127 lines
6.0 KiB
Markdown
127 lines
6.0 KiB
Markdown
---
|
|
language: de
|
|
profile: german
|
|
sections:
|
|
relationships: Beziehungen
|
|
see_also: Siehe auch
|
|
footnotes: Fußnoten
|
|
---
|
|
|
|
# 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
|
|
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](../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](../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](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](../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.
|