stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)
Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
This commit is contained in:
+52
-38
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: types/type-spec.md
|
||||
name: concept
|
||||
description: Basistyp für Concept-Seiten - Architekturen, Muster, Protokolle, Abläufe, Entscheidungen oder Problemstellungen
|
||||
description: Base type for concept pages - architectures, patterns, protocols, workflows, decisions or problems
|
||||
schema: types/concept.schema.yaml
|
||||
subtype_field: concept_type
|
||||
base_dir: concepts
|
||||
@@ -17,49 +17,63 @@ layout:
|
||||
|
||||
# Concept
|
||||
|
||||
`concept` ist der Typ für abstrakte Ideen, Methodiken, Muster und Architekturentscheidungen. Concepts liefern die theoretische und methodische Grundlage, die Entities umsetzen oder befolgen.
|
||||
`concept` is the type for abstract ideas, methodologies, patterns and architectural decisions. Concepts provide the theoretical and methodological ground that entities implement or follow.
|
||||
|
||||
## Wann zu verwenden
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- Dokumentation eines Architekturmusters oder Entwurfsansatzes
|
||||
- Erläuterung eines Entwurfsmusters oder einer Programmiermethodik
|
||||
- Beschreibung eines Kommunikationsprotokolls oder Standards
|
||||
- Festhalten eines Ablaufs oder Prozesses, der über Projekte hinweg wiederkehrt
|
||||
- Dokumentation einer Architekturentscheidung (ADR) oder Entwurfsentscheidung
|
||||
- Analyse eines wiederkehrenden Problems und seiner Lösungen
|
||||
- [When to use](#when-to-use)
|
||||
- [When NOT to use](#when-not-to-use)
|
||||
- [Frontmatter](#frontmatter)
|
||||
- [Authoring guidance](#authoring-guidance)
|
||||
- [Template](#template)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Wann NICHT zu verwenden
|
||||
## When to use
|
||||
|
||||
- Für konkrete Dinge wie Projekte, Systeme oder Werkzeuge (dann `entity`)
|
||||
- Für Quelldokumente oder eingelesenes Material (dann `source`)
|
||||
- Für vergleichende Analysen konkreter Gegenstände (dann `comparison`)
|
||||
- Documenting an architectural pattern or design approach
|
||||
- Explaining a design pattern or a programming methodology
|
||||
- Describing a communication protocol or standard
|
||||
- Recording a workflow or process that recurs across projects
|
||||
- Documenting an architectural decision (ADR) or design decision
|
||||
- Analysing a recurring problem and its solutions
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For concrete things such as projects, systems or tools (use `entity`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses of concrete subjects (use `comparison`)
|
||||
|
||||
## Frontmatter
|
||||
|
||||
| Feld | Pflicht | Verwendung |
|
||||
| Field | Required | Use |
|
||||
|---|---:|---|
|
||||
| `type` | Ja | `types/concept.md` |
|
||||
| `concept_type` | Ja | Eines von: architecture, pattern, protocol, workflow, decision, problem |
|
||||
| `tags` | Nein | Navigations-Tags zur Kategorisierung |
|
||||
| `created` | Ja | Erstellungsdatum (YYYY-MM-DD) |
|
||||
| `modified` | Ja | Datum der letzten Änderung (YYYY-MM-DD) |
|
||||
| `related` | Nein | Titel verwandter Concepts und Entities |
|
||||
| `sources` | Nein | Titel der Source-Seiten, die die Aussagen dieser Seite stützen |
|
||||
| `provenance` | Ja | sourced, general oder mixed |
|
||||
| `summary` | Ja | Einzeiler für `kb/index.md` |
|
||||
| `type` | Yes | `types/concept.md` |
|
||||
| `concept_type` | Yes | One of: architecture, pattern, protocol, workflow, decision, problem |
|
||||
| `tags` | No | Navigation tags for categorization |
|
||||
| `created` | Yes | Creation date (YYYY-MM-DD) |
|
||||
| `modified` | Yes | Date last changed (YYYY-MM-DD) |
|
||||
| `related` | No | Titles of related concepts and entities |
|
||||
| `sources` | No | Titles of the source pages backing this page's claims |
|
||||
| `provenance` | Yes | sourced, general or mixed |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Autorenanweisungen
|
||||
## Authoring guidance
|
||||
|
||||
- Der Titel ist der kanonische Name des Concepts und folgt der etablierten Fachbezeichnung, nicht der KB-Sprache (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" und "Language")
|
||||
- Mit einer klaren Definition beginnen: was das Concept ist
|
||||
- Beispiele geben, wo sie das Verständnis tragen
|
||||
- Auf Entities verlinken, die das Concept umsetzen oder verwenden
|
||||
- Bei `provenance: sourced` oder `mixed` harte Fakten inline mit einer `[^cite-id]`-Fußnote belegen -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` erzeugt Id und Definition
|
||||
- Wikipedia-Tonfall: sachlich, neutral, keine Werbesprache
|
||||
- The title is the concept's canonical name and follows the established term of art, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- Open with a clear definition: what the concept is
|
||||
- Give examples wherever they carry the understanding
|
||||
- Link to the entities that implement or use the concept
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
## Template
|
||||
|
||||
The block below is page material, so it is written in this instance's KB language
|
||||
(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
|
||||
become the headings of every page `wikitool new concept` scaffolds.
|
||||
|
||||
```markdown
|
||||
# {name}
|
||||
|
||||
@@ -94,15 +108,15 @@ TODO: Anti-Muster, Warnungen oder Situationen, in denen es fehl am Platz ist
|
||||
- [[Related Concept 2]]
|
||||
```
|
||||
|
||||
Der Wert hinter `**Typ:**` bleibt der englische Enum-Wert - danach filtert `search --field`.
|
||||
Fügt `wikitool xref` eine Beziehung hinzu, entstehen zusätzlich die beiden toolgeführten
|
||||
Abschnitte für Beziehungen und Querverweise; wie sie heißen, entscheidet die Instanz in
|
||||
The value behind `**Typ:**` stays the English enum value - that is what `search --field` filters
|
||||
on. When `wikitool xref` adds a relationship, the two tool-managed sections for relationships and
|
||||
cross-references appear as well; what they are called is the instance's decision in
|
||||
`kb/CONVENTIONS.md` (`sections:`).
|
||||
|
||||
---
|
||||
|
||||
Ergänzende Hinweise:
|
||||
Additional notes:
|
||||
|
||||
- Concept-Seiten tragen den theoretischen Unterbau des Wikis
|
||||
- Jeder Concept-Typ steht für eine andere Kategorie abstrakten Wissens
|
||||
- Concepts sollten von den Entities aus verlinkt sein, die sie umsetzen oder verwenden
|
||||
- Concept pages carry the wiki's theoretical underpinning
|
||||
- Each concept type stands for a different category of abstract knowledge
|
||||
- Concepts should be linked to from the entities that implement or use them
|
||||
|
||||
Reference in New Issue
Block a user