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 for each sub-section is similar
- Each page starts with a metadata block 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:
Metadata¶
Echo and every md file in this documentation requires a metadata blog at the beginning of the file with this structure:
1 2 3 4 5 6 7 8 9 | |
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.