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
105 lines
4.4 KiB
Plaintext
105 lines
4.4 KiB
Plaintext
---
|
|
# wikitool:template-unfilled - delete this line once the file is answered.
|
|
language: en
|
|
profile: none
|
|
sections:
|
|
relationships: Relationships
|
|
see_also: See Also
|
|
footnotes: Footnotes
|
|
# Headings this instance no longer writes but still recognizes, so a corpus can
|
|
# be translated page by page instead of all at once. Optional; the names this
|
|
# stack wrote before this file existed are always recognized anyway.
|
|
# section_aliases:
|
|
# 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
|
|
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 three headings
|
|
`wikitool xref` and `wikitool cite` write into. Set them before the first page is written:
|
|
afterwards, changing one is a corpus migration rather than an edit.
|
|
|
|
## Language
|
|
|
|
Pages are written in **{language}**. 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`, whose `## Template` blocks are the body skeleton every new page starts
|
|
from. `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).
|
|
|
|
{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 canonical names are the frontmatter's. Any name this instance previously wrote stays
|
|
recognized through `section_aliases:`, which is what lets a corpus be translated page by page.
|
|
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.
|
|
|
|
## 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
|
|
|
|
`tools/wikitool xref add --rel-a/--rel-b` takes a free-text label. Listing the ones this
|
|
instance uses is what keeps a graph typed rather than a wiki full of "related to":
|
|
|
|
{the label vocabulary, in the KB language}
|
|
|
|
No code matches on these, so an old label on an untranslated page 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:
|
|
|
|
{the base score, what raises it, and by how much}
|
|
|
|
{How to hedge in prose at a low score, in the KB language.}
|
|
|
|
## 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. `wikitool doctor` FAILs on a missing or unfilled file, and
|
|
`wikitool docs verify` refuses a `sections:` block that does not name all three slots.
|