Skip to main content

Content Taxonomy

This document defines the canonical taxonomy for all content in the Engineering Journal.

The taxonomy is strictly enforced and defined in .github/taxonomy.yml.

Structure​

The taxonomy consists of:

  • Domains (high-level classification)
  • Tags (controlled vocabulary)

Domains​

Each document MUST have one primary_domain and may have optional secondary_domains.

primary_domain: networking
secondary_domains:
  - troubleshooting

Current allowed domains: governance, networking, security, systems, cloud, devops, troubleshooting, career, learning, personal, academia, knowledge, engineering.

Tags​

Tags MUST:

  • come from the approved taxonomy in .github/taxonomy.yml
  • be relevant to the content
  • be consistent across documents
tags:
  - smb
  - authentication
  - windows

Enforcement​

The following rules are enforced via CI:

  • primary_domain MUST exist in taxonomy
  • secondary_domains MUST exist in taxonomy
  • tags MUST exist in taxonomy
  • Unknown values result in CI failure

Design Principles​

  • Deterministic — all values are controlled and validated
  • Scalable — new domains and tags are added via PR
  • Flexible — domains provide structure, tags provide flexibility
  • Consistent — no free-form tagging allowed

Adding to Taxonomy​

To add a new domain or tag:

  1. Update .github/taxonomy.yml
  2. Submit a PR with label type:chore,area:repo
  3. Ensure naming consistency
  4. Avoid duplicates or synonyms

Anti-Patterns​

Avoid:

  • duplicate tags (e.g., network vs networking)
  • overly broad tags (e.g., misc)
  • redundant domains
  • tagging everything

Related Content​