Skip to main content

Docs Editorial Style Guide

This guide defines the writing and structure conventions used across AEEF docs to keep terminology, navigation, and section boundaries consistent.

Core Principles​

  1. One concept, one canonical name. Do not invent alternate pillar/track/tier names in link text.
  2. State section boundaries explicitly. If a page is conceptual guidance (not implementation), say so.
  3. Give readers a path. High-traffic pages should include Next Steps or equivalent navigation cues.
  4. Separate normative vs practical content. Standards define requirements; tutorials and apply paths show how to implement them.
  5. Prefer stable labels in links. Use canonical page titles or approved short labels.

Canonical Terms​

Pillars​

  • Pillar 1: Engineering Discipline
  • Pillar 2: Governance & Risk
  • Pillar 3: Productivity Architecture
  • Pillar 4: Operating Model
  • Pillar 5: Organizational Enablement

Avoid deprecated aliases (examples):

  • Pillar 4: Measurement & Metrics (incorrect; belongs to Pillar 3)
  • Pillar 4: Continuous Improvement (use Operating Model)
  • Pillar 5: Organizational Alignment (use Organizational Enablement)

Tracks, Tiers, and Guides​

  • Track: program/operating guidance (Transformation, Production)
  • Tier: reference implementation maturity package (Tier 1 Quick Start, Tier 2 Transformation, Tier 3 Production)
  • Guide: role/topic guidance
  • Apply Path: execution-first implementation checklist

Standard Section Labels (Preferred)​

Use these headings where applicable:

  • ## Who This Is For
  • ## What This Section Covers
  • ## Prerequisites
  • ## Start Here by Goal
  • ## Related Pages or ## Related Sections
  • ## Next Steps

Notes:

  • Not every page needs every heading.
  • Root/overview pages SHOULD include Start Here by Goal and Next Steps.
  • Role index pages SHOULD include Related Sections and Next Steps.

Link Text Conventions​

  • Prefer canonical names in link text (Pillar 2: Governance & Risk)
  • If using short labels, ensure they remain unambiguous (Pillar 2)
  • Do not label a link as Pillar 4 if it routes to /pillars/pillar-3-productivity/
  • Prefer descriptive labels over click here

Normative vs Practical Pages​

Normative pages (e.g., PRD-STD standards)​

Should:

  • define requirements and scope
  • use RFC 2119 language consistently
  • point to tutorials/apply paths for implementation

Should not:

  • drift into stack-specific setup unless clearly marked as implementation guidance examples

Practical pages (tutorials, apply paths, tool guides)​

Should:

  • explain what users can do now
  • link to the normative standard source
  • include concrete next actions

Use consistent frontmatter fields:

  • title
  • description
  • sidebar_position (where relevant)

Optional (for future automation/UI badges):

  • doc_type (overview, standard, tutorial, apply-path, role-guide, tool-guide)
  • content_class (normative, practical, reference)

Editorial Style​

  • Use concise, direct language.
  • Prefer active voice.
  • Use AI-assisted consistently.
  • Keep examples production-realistic when possible.
  • Avoid overstating autonomy where human checkpoints are mandatory.

Quality Checks (Local)​

Run before submitting doc-heavy PRs:

npm run check:docs-quality
npm run build

Governance and Maintenance Cadence​

  • Quarterly: docs architecture review (section boundaries, canonical pages, terminology drift)
  • Quarterly: re-run benchmark/source review for high-visibility claims
  • As-needed: update terminology checks when canonical labels evolve
Last updated on by BalrogEg