CCCHH/ansible-infra
CCCHH/ansible-infra
2
2
Fork 1
Code Issues 7 Pull requests 9 Wiki Activity Actions

Add documentation style outline #97

Open
forestcat-admin wants to merge 3 commits from docs-outline-style into main
pull from: docs-outline-style
merge into: CCCHH:main
Conversation 1 Commits 3 Files changed 2 +9 -2
1 changed files with 9 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 8892f9e3bb - Show all commits

clarify the usage of the document scope and the differences between concept, configuration and guide
Some checks failed
/ Ansible Lint (pull_request) Successful in 2m32s
Details
/ Ansible Lint (push) Successful in 2m32s
Details
/ build (pull_request) Has been cancelled
Details

Prev Next
forestcat-admin 2026-05-24 02:55:58 +02:00
commit 8892f9e3bb
Signed by: forestcat-admin
SSH key fingerprint: SHA256:mOzNhGmqziBnfFtROKgKZqGLIXufXmWsvIVEloawS0o

11
docs/concepts-and-configurations/documentation-structure.md
View file

@ -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"