Documentation

Shoehorn provides a unified documentation viewer that aggregates READMEs, runbooks, changelogs, and API specs from your services into a single browsable interface.

How Documentation Is Discovered

Source	What’s Fetched	Configuration
GitHub	README.md files	GITHUB_README_PATTERNS env var
Manifests	Changelog path, runbook paths	integrations.changelog.path, integrations.runbooks
Annotations	Changelog path	shoehorn.dev/changelog-path K8s annotation
Interfaces	OpenAPI, gRPC proto, GraphQL schema URLs	interfaces section in manifest
Frontmatter	category, title, description, related_entities	YAML block at the top of any indexed Markdown file. See Docs Frontmatter.

Viewing Documentation

Entity Detail Page

Navigate to any entity and click the Documentation tab to see:

• README: Rendered Markdown from the repository
• Changelog: Parsed changelog entries
• Runbooks: Operational runbooks with severity levels
• API Docs: Embedded OpenAPI viewer or schema browser

Documentation Health

Navigate to Governance > Documentation to see organization-wide documentation coverage:

• Which entities have READMEs
• Which are missing runbooks
• Stale documentation (not updated in 90+ days)

Configuring Documentation Paths

In Manifests

integrations:
  changelog:
    path: CHANGELOG.md

docs:
  readme:
    path: README.md

In Kubernetes Annotations

annotations:
  shoehorn.dev/changelog-path: "services/my-service/CHANGELOG.md"

This is useful in monorepo setups where each service has its own changelog.

Documentation Freshness

Status	Criteria
Fresh	Updated within 30 days
Aging	Updated 30-90 days ago
Stale	Not updated in 90+ days

Stale documentation triggers governance actions if documentation governance rules are active.