fix: merge Mathias' chapter with existing docs chapter

chapters/development/documentation.md

@@ -65,6 +65,17 @@ Then add (if applicable):
 - links to the relevant issue tracker/project management systems, and
 - badges to CI status.
 
+###### Docs-as-code
+
+Documentation `SHOULD` be placed within the software repository.
+Furthermore for the documentation writing, building, testing and publication process, all quality criteria, workflows
+and pipelines `SHOULD` be set up alike those for the software itself.
+In this way documentation is treated the same way as code including the usage of version control, issue tracker,
+code reviews and automated tests.
+
+A presentation of the usage of this approach for a long-term scientific software project is available at [zenodo](https://zenodo.org/records/7260347).
+In general, this approach can be applied to small-scale projects as well.
+
 ##### Doc Sprints
 
 To ensure thorough documentation of our code doc sprints or other meetings specifically targeted at writing docs can be organized.
@@ -73,7 +84,7 @@ To ensure thorough documentation of our code doc sprints or other meetings speci
 
 ###### Software Architecture
 
-Each software project `SHOULD` provide an architecture diagram that helps to understand its basic functionality.
+Each software project `SHOULD` provide an architecture diagram that represents its major components and their interaction.
 In some cases using tools to generate diagrams such as UML class diagrams may not be possible.
 
 *Examples:*

chapters/documentation.md

-## Documentation
-
-Several aspects of documentation are related to the life-cycle of our products. As a very basic foundation, it is mandatory to have a kind of in-place documentation, for example by appropriately verbose function documentation.
-
-A good documentation `SHOULD` focus on several target groups (when applicable): developer, operator and user of the software.
-Also it is `RECOMMENDED` to create and update a general overview of the software architecture accompanied by at least one
-graphical representation of the major components and their interaction.
-
-### Docs-as-code
-
-Documentation should be placed within the software repository. Furthermore for the documentation writing, building, testing and publication process, all quality criteria, workflows and pipelines `SHOULD` be set up alike those for the software itself. In this way documentation is treated the same way as code including the usage of version control, issue tracker, code reviews and automated tests.
-
-A presentation of the usage of this approach for a long-term scientific software project is available at [zenodo](https://zenodo.org/records/7260347). In general, this approach can be applied to small-scale projects as well.
-
-Docs-as-code is not an out-of-the-box environment for creating neat documentation. It is up to the project to decide for a markup format and a static site generator.