#1 Add documentation guidelines

docs/how-to-write-docs.md

+---
+title: Guidelines
+repo: https://gitlab.lakedrops.com/devops-tools/documentation
+issues: https://gitlab.lakedrops.com/devops-tools/documentation/-/issues
+tags: documentation, devops, tools
+---
+# How to write documentation on this platform
+
+Please make yourself familiar with these guidelines and follow them as best as
+possible, so that we can collaborate and still keep the quality up for the best
+benefit of all users.
+
+## Principles
+
+- GitLab projects
+    - Each project gets at least one page of its own in this framework, sub-pages may be added if the amount of documentation is too much for a single page
+    - The projects don't come with readme file anymore
+    - The link to its documentation will be added to the project description: `[Documentation](https://devops-tools.docs.lakedrops.com/section/subsection/project/)`
+    - Wikis won't be used anymore, as they fragmented all the content across multiple projects and haven't been helpful to the users
+    - Changelogs will not be maintained in GitLab anymore, they are part of the documentation
+- Documentation sections and pages
+    - Each tool category has their own section
+    - In each section, each tool has their own sub-section
+    - The [information architecture](#information-architecture) for each sub-section is similar
+    - Each page starts with a [metadata block](#metadata) in Yaml format
+
+## Information architecture
+
+This section is currently under review and will be updated soon.
+
+## Markdown documentation for MkDocs
+
+For editors, these links may be helpful:
+
+- [Writing documentation](https://www.mkdocs.org/user-guide/writing-your-docs/)
+    - [Links](https://www.mkdocs.org/user-guide/writing-your-docs/#internal-links)
+    - [Meta-Data](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data)
+    - [Tables](https://www.mkdocs.org/user-guide/writing-your-docs/#tables)
+
+## Metadata
+
+Echo and every md file in this documentation requires a metadata blog at the
+beginning of the file with this structure:
+  
+```yaml
+---
+title: My Document
+repo: https://gitlab.lakedrops.com/devops-tools/documentation
+issues: https://gitlab.lakedrops.com/devops-tools/documentation/-/issues
+tags: documentation, devops, tools
+---
+```
+
+The title field is mandatory, all others are optional but should be used when
+ever possible.
+
+## Allowed tags
+
+Tags are very helpful, but only if used wisely. One part of this is that not
+every author and page uses their own tags. Therefore, only the following list
+of tags is allowed:
+
+- ansible
+- ci/cd
+- composer
+- devops
+- docker
+- docker-compose
+- documentation
+- drupal
+- gitlab
+- installation
+- node
+- testing
+- tools
+- troubleshooting
+
+If new tags are required, please propose them in the [issue queue](https://gitlab.lakedrops.com/devops-tools/documentation/-/issues).
+
+## For developers and technical maintainers of this framework
+
+- [Installation](https://www.mkdocs.org)
+- [Configuration](https://www.mkdocs.org/user-guide/configuration/)

docs/index.md

@@ -8,18 +8,14 @@ through the menu on the left or search with the tool in the header.
 Documentation is always moving. If you've found any mistake or have other
 things to either critize or improve, please got to the
 [Documentation Repository](https://gitlab.lakedrops.com/devops-tools/documentation)
-and either open an issue or start a MR (merge request) to propose your changes.
+and either [open an issue](https://gitlab.lakedrops.com/devops-tools/documentation/-/issues)
+or start a [merge request](https://gitlab.lakedrops.com/devops-tools/documentation/-/merge_requests) to propose your changes.
+
+Please review [the guidelines on how to write documentation](how-to-write-docs.md)
+on this platform.
 
 ## Other noteworthy links
 
 - [Our homepage](https://www.bitegra-solutions.de/en)
 - [Imprint](https://www.bitegra-solutions.de/en/node/21)
 - [Chat channel](https://mattermost.lakedrops.com/paragon/channels/devop-tools)
-
-## Links helpful MkDocs resources
-
-- [Configuration](https://www.mkdocs.org/user-guide/configuration/)
-- [Writing documentation](https://www.mkdocs.org/user-guide/writing-your-docs/)
-    - [Links](https://www.mkdocs.org/user-guide/writing-your-docs/#internal-links)
-    - [Meta-Data](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data)
-    - [Tables](https://www.mkdocs.org/user-guide/writing-your-docs/#tables)