Knowledge Architecture Standards & Metadata Model

Purpose and scope

This playbook defines lightweight, pragmatic standards for knowledge architecture so teams can find, reuse, and maintain content without excessive overhead. It is intentionally minimal: prefer a few consistent fields and simple rules that people will actually keep updated. Use these patterns as starting points and adapt them to local needs.

Why this matters

Consistent metadata and predictable content types reduce duplicate work, speed search and discovery, clarify ownership, and make it easier to automate quality checks, audits, and migrations.

Minimal required metadata model

Require only the fields teams will reliably maintain. Store these as front-matter, repository metadata, CMS fields, or platform attributes.

• title (string) — human-friendly short name.
• contentType (enum) — one of the approved content types (see list below).
• owner (person or team id) — who is accountable for correctness and review cadence.
• audience (string or tag list) — primary intended readers (e.g., field-teams, managers).
• tags (list) — lightweight topic tags for discovery and faceted search.
• lastValidated (date) — date the content was last checked for accuracy.
• dependencies (list of references) — links to related policies, data sources, or systems the content depends on.

Optional helpful fields:

• status (draft/review/published/deprecated/archived)
• version (string)
• summary (short paragraph)
• estimatedEffort (hours) — for work instructions or SOPs.

Approved content types

Use a small, clear set of content types so consumers know what to expect:

• Article (conceptual explanation)
• Guide / Playbook (how to approach a problem)
• How-to / Procedure (step-by-step)
• Template (starter file)
• Checklist / Audit
• Policy / Standard
• Process (visual + roles + steps)
• Case Study / Postmortem
• FAQ
• Asset (dataset, image, file)

Naming conventions (practical, minimal)

Names should be stable, searchable, and human-readable. Use lowercase with slashes for hierarchical namespaces when repositories support it (e.g., knowledge/quality/oee-basics).

• Short path prefix: team or domain (e.g., ops/, hr/, quality/)
• Title: sentence-case, descriptive (Avoid internal acronyms unless common)
• Examples:
  • quality/oee-overview
  • ops/lockout-tagout-procedure
  • hr/new-hire-onboarding-playbook

Tagging and taxonomy guidance

Keep taxonomies shallow and practical. Prefer tags for cross-cutting topics and a small controlled vocabulary for primary categories.

• Use 3–7 topic tags per item; avoid tag inflation.
• Maintain a central tag guidance list and a simple process for adding tags.
• Capture audience and domain as separate fields, not as generic tags.

Linking, dependencies, and reuse patterns

Encourage explicit links. When content reuses another item, reference it in dependencies and include the relationship (e.g., "adapts", "implements", "derived-from").

Reuse pattern examples:

• One canonical policy referenced by multiple local procedures (inheritance).
• Templates stored as assets with a version field and a changelog.
• Playbooks that include or embed checklists to support operational use.

Minimal lifecycle and archive rules

Keep lifecycle simple so people follow it:

1. Draft — being created or edited.
2. In Review — assigned reviewer(s) checking for correctness and compliance.
3. Published — ready for use; required metadata present.
4. Deprecated — superseded; marked with recommended alternatives.
5. Archived — removed from active navigation but retained for history.

Archive rule: if lastValidated is older than 24 months for operational content, flag for review or auto-deprecate after owner confirmation.

Lightweight governance roles and responsibilities

• Owner — accountable for accuracy and reviews (required).
• Author/Contributor — creates or updates content.
• Reviewer — validates technical accuracy, safety, or compliance.
• Publisher — performs final publication steps (may be the owner).
• Archivist — manages archived content and retention rules (optional).

Keep role counts small. Ideally a single named owner per item with an owning team contact.

Review cadences and validation

Assign cadences according to content criticality:

• High-risk operational content: review every 6–12 months.
• Procedures and SOPs: every 12 months or after any incident/change.
• Guides and conceptual articles: every 18–24 months.

Record the cadence in the owner's team guidelines and rely on lastValidated to trigger reminders or automated checks.

Versioning and permissions

Use semantic versioning for procedures when changes affect execution. Keep an accessible changelog for notable edits. Permissions should follow least-privilege: most content editable by contributors with a review/publish gate for critical items.

Examples — good and bad

Good example

<front-matter>
title: "Lockout/Tagout Procedure"
contentType: "Procedure"
owners: ["facility-maintenance-team"]
audience: ["technicians","maintenance"]
tags: ["safety","LOTO"]
lastValidated: "2026-04-10"
dependencies: ["policy/energy-isolation"]
status: "Published"
</front-matter>

Clear title, single owning team, tags for discovery, dependency linked to policy, recent validation date.

Bad example

Title: "LOTO"
No owner, no tags, unclear audience, no last validated date, stored with an unrelated filename like 2021_instructions.docx

Quick repository onboarding script (conceptual)

Use this as a checklist or adapt the snippet to your platform. This is an example of the steps needed to bring an existing repo into compliance — it is conceptual, not a required executable. Implement as a migration job in your CMS, a batch script, or a small integration.

1. Scan repository for content files (markdown, docs, templates).
2. Extract existing metadata (front-matter or header info).
3. Map existing fields to the minimal model; populate missing required fields with placeholders and tag for owner assignment.
4. Create a short validation report listing items missing owners, tags, or lastValidated dates.
5. Run owner-assignment workflow and schedule initial reviews.
6. Optionally, create an "onboarded" tag or field once items meet minimal standards.

#!/bin/sh
# PSEUDO: list files and add missing metadata placeholders
for f in $(find content -name "*.md"); do
  if ! grep -q "lastValidated" "$f"; then
    echo "Adding placeholder lastValidated to $f"
    # Add front-matter or touch metadata (implement per CMS)
  fi
done
# Generate report: missing-owner.csv

Practical adoption tips

• Start with one team and one content type (e.g., procedures) and refine the model before scaling.
• Automate reminders using lastValidated and the platform's notification features.
• Provide a simple interactive form for authors to create new content that enforces required metadata (see Capability notes below).
• Hold a short onboarding workshop for owners and frequent contributors.

Checklist — minimal bar for publication

1. Title present and descriptive
2. contentType set from approved list
3. Owner assigned (person or team)
4. Audience or primary users specified
5. At least one tag present
6. lastValidated present (or scheduled within 30 days)
7. Dependencies listed if the content relies on other items
8. Status set to Published

Use this playbook as a baseline. Keep the model intentionally small and evolve it as teams show real needs—avoid over-engineering.