torben
177c7e9ce8
Files changed: - .gitea/workflows/ci.yml - AGENTS.md - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/link-taxonomy.md - instructions/migrations/4.0.0-link-taxonomy.md - instructions/setup-instance.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/blocks.py - tools/chemenu/cli.py - tools/chemenu/commands/cite_cmd.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/links_cmd.py - tools/chemenu/commands/migrate_cmd.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/page_ops.py - tools/chemenu/commands/run_budget.py - tools/chemenu/commands/xref.py - tools/chemenu/conventions.py - tools/chemenu/corpus_diff.py - tools/chemenu/frontmatter_io.py - tools/chemenu/kb_collections.py - tools/chemenu/kb_state.py - tools/chemenu/links.py - tools/chemenu/lint_core.py - tools/chemenu/provenance.py - tools/chemenu/sections.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_blocks.py - tools/chemenu/tests/test_cite_cmd.py - tools/chemenu/tests/test_conventions.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_migrate_cmd.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/tests/test_xref.py - types/concept.schema.yaml - types/entity.md - types/entity.schema.yaml - types/instruction.schema.yaml - types/type-spec.md - work/link-taxonomy-migration/README.md - work/link-taxonomy-migration/plan.md
90 lines
3.8 KiB
Plaintext
90 lines
3.8 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}**. 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 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.
|
|
|
|
## 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. `wikitool doctor` FAILs on a missing or unfilled
|
|
file, and `wikitool docs verify` refuses a `sections:` block that does not name both regions.
|