docs: README-Typenbaum und language-boundaries auf den guidance-Split nachgezogen (#104)
CI / verify (push) Failing after 38s
CI / verify (push) Failing after 38s
Files changed: - README.md - docs/language-boundaries.md
This commit is contained in:
@@ -16,7 +16,7 @@ and which argument for it turned out to be wrong.
|
||||
- [Why the control plane's language is English](#why-the-control-planes-language-is-english)
|
||||
- [Why it is not a parameter](#why-it-is-not-a-parameter)
|
||||
- [What the KB language still decides](#what-the-kb-language-still-decides)
|
||||
- [Where the line runs inside one file](#where-the-line-runs-inside-one-file)
|
||||
- [Where the line runs around a page type](#where-the-line-runs-around-a-page-type)
|
||||
- [What would put this back on the table](#what-would-put-this-back-on-the-table)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
@@ -99,15 +99,24 @@ experiences:
|
||||
So an operator who reads no English gets German pages and German answers from an agent reading
|
||||
English instructions. The English is what the machinery is written in, not what it says back.
|
||||
|
||||
## Where the line runs inside one file
|
||||
## Where the line runs around a page type
|
||||
|
||||
One file shape carries both halves, and it is worth knowing which is which before editing it: a
|
||||
page type-spec (`types/entity.md` and its three siblings). Its authoring guidance addresses an
|
||||
agent; its `## Template` block and `layout:` titles become the literal headings of pages; its
|
||||
field names and enum values are identifiers and are translated in neither direction.
|
||||
[types/type-spec.md § Who owns a type-spec](../types/type-spec.md#who-owns-a-type-spec) has that
|
||||
split as a table, and [ownership-and-templates.md](ownership-and-templates.md) § "Where the file
|
||||
boundary strains" has what it costs to keep two audiences in one file.
|
||||
A page type's contract is where the two languages meet most closely, and it is worth knowing
|
||||
which part is which before editing any of it. Its authoring guidance addresses an agent and is
|
||||
English; its `## Template` block and `layout:` titles become the literal headings of pages and
|
||||
follow the KB language; its field names and enum values are identifiers and are translated in
|
||||
neither direction.
|
||||
|
||||
The language line did not move when the *file* line did. A `root: kb` type-spec may now put its
|
||||
authoring guidance in a separate, stack-owned `types/<name>.guidance.md` rather than carrying it
|
||||
beside the template, but that split was made for ownership reasons - so an upgrade can improve
|
||||
the guidance without overwriting what the instance chose - and it leaves this page's argument
|
||||
untouched: each part is still written in the language its own reader needs, and a type-spec that
|
||||
declares no `guidance:` keeps both halves in one file with exactly the same rule applying inside
|
||||
it. [types/type-spec.md § Who owns a type-spec](../types/type-spec.md#who-owns-a-type-spec) has
|
||||
the split as a table, and [ownership-and-templates.md](ownership-and-templates.md) § "Where the
|
||||
file boundary used to strain" has what it cost to keep two audiences in one file for as long as
|
||||
it did.
|
||||
|
||||
## What would put this back on the table
|
||||
|
||||
|
||||
Reference in New Issue
Block a user