torben
d49513bda6
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
1.9 KiB
1.9 KiB
type, name, description
| type | name | description |
|---|---|---|
| types/type-guidance.md | concept | When to write a concept page instead of a neighboring type, and how to write a conforming one - citation, linking and register rules that hold regardless of which concept_type values this instance chose |
Concept Guidance
concept is the type for abstract ideas, methodologies, patterns and architectural decisions.
Concepts provide the theoretical and methodological ground that entities implement or follow.
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)
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: sourcedormixed, 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
Relevant 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