How and which tags to use?
This document explains why we use tags in our documentation and how we keep them structured. The goal is to help readers understand the role of tags and why we enforce rules around them.
Concept
Tags allow us to group related articles together, making it easier for users to discover and logically build knowledge across different documentation categories.
Why
While tags are powerful, uncontrolled usage can quickly become messy. Too many tags, overlapping meanings, or unclear wording can confuse readers and reduce the value of the documentation. By maintaining a controlled list of approved tags, we ensure consistency and prevent fragmentation.
Tag list overview
| Tag | Description | Example Usage |
|---|---|---|
aws | Any AWS-related content | How-to deploy an S3 bucket with TF |
kubernetes | Kubernetes-specific topics | Tutorial on running pods on EKS |
helm | Helm chart usage and configuration | Reference on Helm values for Imgproxy |
terraform | Terraform usage and modules | How-to about How to update a Terraform provider |
security | Security-related topics | Explanation about IMDSv2 requirements |
finops | FinOps practices, Cost savings, … | Explanation about Reservations vs SPs |
observability | FinOps practices, Cost savings, … | References or explanations about Grafana, Loki, … |
skyscrapers | Related to Skyscrapers | References, Service offerings, Responsibility model |
Proposing New Tags
When adding new tags, keep in mind that tags should remain useful, clear and consistent. We follow a two-level approach:
General tags (
aws,kubernetes,terraform)- Broad categories that group a large set of topics.
- These are the entry points into major themes.
Specific tags (namespaced) (
aws_iam,aws_rds,terraform_sqs)- Use when a general tag is too broad and many docs cluster around a subtopic.
- Always prefix with the parent (
aws_*,terraform_*) to keep consistency. - Avoid creating a specific tag if only one doc would use it. At least 2 docs should reference it before it’s approved.
Process
- Open a PR updating this file.
- Add the new tag in the Tag list overview table.
- Link at least 2 documents that will use it.
- Get review approval before merging.
Conclusion
We use tags to connect content across the documentation in a logical way. This way we keep a clean hierarchy of tags that can grow as the documentation grows.