03 Knowledge Standards

Knowledge Standards

Purpose

This document defines the standards for creating and maintaining high-quality knowledge artefacts in the Company Handbook.

Core Principles

1. Single Source of Truth (SSOT)

Each piece of information should exist in exactly one authoritative location:

• Avoid duplication: Link to content, don’t copy it
• Auto-populate listings: Use page-list code blocks instead of manually maintaining child page lists. See Auto-Populated Listings.
• Clear ownership: Every document has an identified owner
• Canonical location: Follow the governance model for placement

2. MECE Classification (Mutually Exclusive, Collectively Exhaustive)

Content must be classifiable into exactly one category:

• Use the Content Types taxonomy
• Each artefact fits in exactly one of: Policy, Process, Procedure, Guide, Template, or Decision
• If classification is unclear, the taxonomy needs refinement

3. Progressive Disclosure

Structure content from general to specific:

• Start with purpose and context
• Provide overview before details
• Use links for deep dives
• Include examples and diagrams

4. Metadata-First

Every document must include frontmatter:

---
publish: true|false # Controls Quartz publishing (required)
page-status: [draft|review|active|deprecated]
created: YYYY-MM-DD
owner: [team-slug]
type: [content-type]
version: [if applicable]
---

Structural Standards

Folder Organization

Follow the approved content structure:

content/
├── 00 Governance/     # Company-wide governance
├── 01 Value Streams/          # Cross-functional flows
│   └── [Value Stream]/
│       ├── README.md          # Value stream landing page
│       └── ...
├── 02 Guilds/                 # Domain-based organization
│   └── [Guild]/
│       ├── README.md          # Guild landing page
│       ├── Practices/
│       │   ├── README.md      # Practices listing page
│       │   └── [Practice]/
│               ├── README.md       # Practice landing page
│               ├── 01 Policies/
│               ├── 02 Processes/
│               ├── 03 Procedures/
│               ├── 04 Guides/
│               └── 05 Templates/
│       └── Roles/                  # Role criteria owned by this guild
│           ├── README.md
│           ├── [Role Type]/        # Primary roles (e.g., Engineer/)
│           │   └── [Level].md      # One criteria file per level
│           └── Cross-Guild/        # Criteria contributed to other guilds' roles
│               └── [Role Type]/
│                   └── [Level].md
├── 03 Products/       # Product documentation
│   ├── README.md              # Products landing page
│   └── [Product]/
│       ├── README.md          # Product landing page
│       └── ...
├── 99 Archive/                # Deprecated content
└── _authoring/                # Internal authoring artifacts (excluded from publish)
    ├── decisions/             # Architectural Decision Records (ADRs)
    ├── diagrams/              # Shared diagrams (Excalidraw, Mermaid templates)
    ├── reference/             # Reference term definitions
    ├── plans/                 # Implementation plans
    ├── templater/             # Obsidian document templates
    └── ...

Naming Conventions

Files:

• Use Title Case: Customer Onboarding Process.md
• Be descriptive: Avoid doc1.md, use Incident Response Procedure.md
• No special characters except hyphens and spaces

Folders:

• Use numbered prefixes for artefact categories: 01 Policies/, 02 Processes/
• Governance artifacts (diagrams, plans, decisions, specs) are centralized in content/_authoring/ — these are excluded from publish
• Use descriptive names: HR Management/, not TM/
• Every folder must contain at least one .md file (typically README.md) to serve as the folder landing page. When a folder is clicked in the published site, the README.md file is rendered as the folder page. Folders with only subfolders and no .md files will fall back to a generic navigation listing.

Auto-Populated Listings

Use page-list code blocks to generate automatic child page listings instead of manually maintaining lists:

```page-list
path: 02 Guilds/GL03 Delivery Guild/Practices
sort: filename
```

Directives:

• path: (required) — Folder path relative to content/
• sort: (optional) — Sort by title, created, or filename (default: title)
• depth: (optional) — Scan depth, 1 = direct children only (default: 1)

When to use:

• Index pages listing child pages (guilds, practices, value streams)
• Overview pages listing sibling practices
• Any listing that should automatically update when pages are added/removed

When NOT to use:

• Curated cross-references (e.g., a value stream listing its coordinated practices from different guilds)
• Static reference tables
• Listings that require custom descriptions not found in frontmatter

Criteria Aggregation Listings

Use criteria-list code blocks to aggregate role criteria from distributed criteria files across Guild Roles/ directories:

```criteria-list
role: Engineer
level: L3
mode: summary
```

Directives:

• role: (required) — Role type to aggregate criteria for (e.g., “Engineer”)
• level: (required) — Seniority level code (e.g., “L1”, “L2”, “L3”, “L4”, “L5”)
• mode: (required) — Rendering mode: summary (aggregated counts per practice) or detail (full criteria with score fields)

Scanning logic:

1. Scans all 02 Guilds/*/Roles/ directories recursively
2. Finds .md files where frontmatter type == "role-criteria", role matches, and level matches
3. Groups criteria by guild and management practice (subarea)
4. Sorts by guild name, then practice name

When to use:

• Evaluation Workbook templates that aggregate criteria from multiple guilds
• Any page that needs to display aggregated role criteria

When NOT to use:

• Displaying criteria from a single file (use a standard table instead)
• Non-criteria content aggregation (use page-list instead)

Role Criteria Files

Role criteria files define the competency expectations that a Guild has for a specific role at a specific level. They use a structured frontmatter schema for metadata and standard markdown tables in the file body for the criteria definitions.

Frontmatter:

---
publish: true
page-status: draft
created: YYYY-MM-DD
owner: [guild-slug]
type: role-criteria
guild: [GL0X Guild Name]
role: [Role Type]
level: [L1-L5]
level-title: [Display Name]
criteria-type: primary|secondary
---

Body (criteria as markdown tables):

Criteria are authored as standard human-readable markdown tables, grouped under H2 or H3 headings that name the Management Practice. The criteria-list plugin parses these tables directly — no special code blocks or structured data formats are needed.

Each table must have two columns: ID and Criterion. The plugin identifies criteria rows by matching the ID pattern L\d+-[A-Z] (e.g., L3-DEV01). The heading above each table is used as the Management Practice (subarea) name.

Example body structure:

# L3 Lead Engineer — Technology Guild Criteria
 
Description paragraph...
 
## Criteria by Management Practice
 
### Software Eng
 
| ID       | Criterion                                             |
| -------- | ----------------------------------------------------- |
| L3-DEV01 | Contributes to standards for architecture and design. |
| L3-DEV02 | Codes, fixes, and documents large complex systems.    |
 
### Solution Eng
 
| ID      | Criterion                                          |
| ------- | -------------------------------------------------- |
| L3-DD01 | Can read and understand standard design documents. |

Heading conventions:

• Primary role files (GL04 Technology Guild) use ## Criteria by Management Practice as a wrapper heading, with ### [Practice Name] subheadings. The plugin skips the wrapper heading and uses the H3 headings as subarea names.
• Cross-guild files (GL02, GL03) use direct ## [Practice Name] headings with no wrapper.

Key conventions:

• type: role-criteria identifies the file for the criteria-list plugin
• criteria-type: primary for the guild that owns the role; secondary for cross-guild contributions
• Heading values must match the directory name of the corresponding Management Practice (e.g., “Software Eng”, not “Software Eng Management”)
• One file per role-level per guild (e.g., GL04/Roles/Engineer/L3 Lead Engineer.md)
• Cross-guild criteria live at [Source Guild]/Roles/Cross-Guild/[Role Type]/[Level].md
• Criteria are defined only in markdown tables — no frontmatter arrays or special code blocks

Required Document Sections

Every artefact should include:

1. Title (H1, matches filename)
2. Purpose (Why this document exists)
3. Scope (What’s in/out of scope)
4. Main Content (Structured with H2/H3 headings)
5. Related Resources (Links to related content)
6. Metadata Footer (Version, last updated, owner)

Content Quality Standards

Writing Style

• Clear and Concise: Get to the point quickly
• Active Voice: “Deploy the application” not “The application should be deployed”
• Present Tense: “The system validates” not “The system will validate”
• Define Acronyms: On first use in each document
• Consistent Terminology: Use established company terms

Formatting

• Headings: Use H1 for title, H2 for sections, H3 for subsections
• Lists: Use bullet points for unordered, numbers for sequential steps
• Code: Use code blocks with language specified: yaml
• Tables: Use markdown tables for structured data
• Links: Use standard Markdown links for all internal navigation: [Display Name](slug). The slug is the target filename without .md, with spaces replaced by hyphens (e.g. [How to Contribute](01-How-to-Contribute)). For links with anchors: [Section Name](slug#heading-slug). Do not use Obsidian wikilink syntax ([[...]]).

Diagrams and Visuals

• Store in _authoring/diagrams/ folder (centralized authoring directory)
• Use standard tools: Excalidraw, Draw.io, Mermaid
• Include alt text for accessibility
• Embed with clear captions

Versioning Standards

When to Version

Version control is required for:

• Policies: Major changes require new version (v1.0 → v2.0)
• Processes: Significant restructuring requires versioning
• Decisions: Never versioned (immutable; create new decision to supersede)

Version Numbering

Use semantic versioning:

• Major (X.0): Breaking changes, complete rewrites
• Minor (X.Y): New sections, significant additions
• Patch (X.Y.Z): Typo fixes, clarifications (optional)

Version Management

• Include version in frontmatter: version: 2.1
• For major versions, consider including in filename: Security Policy v2.0.md
• Archive superseded versions to 99 Archive/
• Add redirect note in archived location

Review and Maintenance

Review Cadence

• Policies: Annual review (minimum)
• Processes: Quarterly review
• Procedures: As-needed review (when changes occur)
• Guides: Bi-annual review
• Templates: As-needed review
• Decisions: No scheduled review (immutable)

Status Lifecycle

1. Draft: Initial creation, work in progress
2. Review: Submitted for approval, under review
3. Active: Approved and in use
4. Deprecated: Superseded, retained for reference

Update page-status in frontmatter as status changes.

Governance and Ownership

Ownership Model

Every artefact has an owner:

• Policies: Practice Owner or Guild Lead
• Processes: Practice Owner
• Procedures: Practice Owner or designated Subject Matter Expert
• Guides: Practice Owner or designated author
• Templates: Practice Owner
• Decisions: Practice Owner or Architecture Team

Approval Authority

Content Type	Approval Required From
Company Governance	Leadership Team
Guild Overview	Guild Lead
Practice Artefacts	Practice Owner
Value Stream Docs	Value Stream Owner
Product Docs	Product Owner

Compliance Requirements

All Artefacts Must:

✅ Include required frontmatter
✅ Follow folder structure
✅ Use approved templates
✅ Have identified owner
✅ Pass CODEOWNERS review (when implemented)
✅ Have no broken links
✅ Follow naming conventions
✅ Include change log (for versioned content)

Enforcement

• Automated checks via CI/CD — the validate-content.yml workflow validates frontmatter and checks for duplicate codes on all PRs touching content/
• Automated scaffolding — new Value Streams and Management Practices are created via GitHub Issue Forms, which trigger validation, MECE analysis, and scaffolded PRs (see Plan 08)
• Manual review via PR approval process
• Periodic audits by Guild Leads

Related Resources

• How to Contribute
• Decision Process
• Content Types Taxonomy

---

Version: 1.0
Last Updated: 2026-02-11
Maintained By: Leadership Team