One best practice we follow regarding documentation is to keep it close to what it describes, we prefer including those files together with the actual code, in a different docs/
folder. We write them in Markdown because it is a simple and easy to understand format that is automatically rendered correctly when browsing those files in Gitlab.
And because we are Gitlab users, we are also able to use other features like Gitlab pages and the mermaid
support in markdown to generate even better and useful documentation.
Using mkdocs for generating public documentation
There is Gitlab repository that demonstrates this process, important bits about this specific repository are:
.gitlab-ci.yml
configuration explicitly using the forked image and copying the CSS fixes before the build, and- mkdocs-mermaid forked plugin that includes specific fixes for the bundle
readthedocs
theme and docker support.
The final result:
- mkdoc documentation using readthedocs and, the equivalent
- Gitlab markdown rendered