diff --git a/docs/concepts-and-configurations/documentation-structure.md b/docs/concepts-and-configurations/documentation-structure.md index dc4919f..30d2ebe 100644 --- a/docs/concepts-and-configurations/documentation-structure.md +++ b/docs/concepts-and-configurations/documentation-structure.md @@ -16,13 +16,20 @@ Rules are formatting and writing decisions that apply to every document. Their g - The documentation structure is intended to be followed, while not being **enforced** to keep a low entry barier for documentation authors. - Use features like _Admonitions_ given by markdown and the theme whenever they can help by increasing the readability and outlining important parts. For instructions on how to use these theme specific features please refer down to the _MkDocs shadcn_ documentation in the References section. -## Document Scope -The scope for a concept document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. +## Defining a Document Scope +The scope for a document should be set to define responsibility and set boundaries to where that document applies. Especially lining out which services are affected by it. It **does not** need to be defined explicitly in the text, but should be kept in mind while writing. !!! note "Example" The scope for this document is aiming to convey the base concepts on how to structure concepts and configurations in this documentation. To provide high readability and a project wide concise structure that authors and readers can rely on. +We decide in this documentation between concepts, configurations and guides. Their separation should be clearified with folowing list: + +- **Concept:** A concept includes an abstract definition about a specific structure while not going into implementation details. +- **Configuration:** A configuration can be a follow up of a concept, explaining the specific implementation in a given environment. +- **Guide:** A guide is a step-by-step hands-on instruction for the reader to follow along. It can reference concepts and configurations. + + ## Structuring Concepts !!! note "Goal"