Skip to content

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
---
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.

For developers and technical maintainers of this framework


Last update: January 12, 2021 17:21:01