types/: Seiten-Type-Spec-Anleitungsprosa in stackeigene guidance-Datei ausgelagert (schliesst #104)
Files changed: - AGENTS.md - CHANGES.md - VERSION - docs/ownership-and-templates.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/setup-instance.md - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/types_cmd.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_dist_upgrade.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - tools/chemenu/type_resolver.py - tools/chemenu/types_core.py - types/comparison.guidance.md - types/comparison.md - types/concept.guidance.md - types/concept.md - types/entity.guidance.md - types/entity.md - types/source.guidance.md - types/source.md - types/type-guidance.md - types/type-guidance.schema.yaml - types/type-spec.md
This commit is contained in:
+5
-44
@@ -6,6 +6,7 @@ schema: types/concept.schema.yaml
|
||||
subtype_field: concept_type
|
||||
base_dir: concepts
|
||||
page_ref_fields: [related, sources]
|
||||
guidance: types/concept.guidance.md
|
||||
layout:
|
||||
architecture: {dir: architectures, title: Architekturen}
|
||||
pattern: {dir: patterns, title: Muster}
|
||||
@@ -17,32 +18,10 @@ layout:
|
||||
|
||||
# Concept
|
||||
|
||||
`concept` is the type for abstract ideas, methodologies, patterns and architectural decisions. Concepts provide the theoretical and methodological ground that entities implement or follow.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [When to use](#when-to-use)
|
||||
- [When NOT to use](#when-not-to-use)
|
||||
- [Frontmatter](#frontmatter)
|
||||
- [Authoring guidance](#authoring-guidance)
|
||||
- [Template](#template)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## When to use
|
||||
|
||||
- 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`)
|
||||
This instance's configuration for the `concept` type: its frontmatter fields as this schema
|
||||
requires them, and the page skeleton `wikitool new concept` scaffolds. When to use this type and
|
||||
how to write a conforming page is [types/concept.guidance.md](concept.guidance.md) -
|
||||
`tools/wikitool types describe concept` composes both into one answer.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
@@ -58,16 +37,6 @@ layout:
|
||||
| `provenance` | Yes | sourced, general or mixed |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Authoring guidance
|
||||
|
||||
- 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
|
||||
@@ -112,11 +81,3 @@ The value behind `**Typ:**` stays the English enum value - that is what `search
|
||||
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:`).
|
||||
|
||||
---
|
||||
|
||||
Additional notes:
|
||||
|
||||
- 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