docs(handbook): document our SDLC across planning, design, implementation, and monitoring

[scotwells]

Summary

• Ties the handbook's existing scattered process pages into one coherent SDLC: Planning → Design → Implementation → Monitoring
• Adds two new pages: build/design.md (system design + API design) and build/standards.md (version control, code review, CI, operational readiness)
• Expands product/roadmap.md (planning phase / definition of ready), product/customers.md (listening to customers / product feedback), and build/production-readiness.md (metrics, logs, traces, alerts, dashboards)
• Adds a short "Our SDLC" overview to build/index.md linking all four phases in order

Test plan

• npm run lint:md passes on all changed/new files
• Preview the handbook pages in a running dev server to check sidebar ordering and rendered links
• Confirm cross-links resolve (/handbook/build/design, /handbook/build/standards, anchor links like #monitoring--observability and #listening-to-customers)

🤖 Generated with Claude Code

[github-actions]

🔎 SEO & Meta Review

Analyzed 13 of 98 built HTML pages (mode: changed-only).

📊 Score summary

Metric	Value
Overall score	🟢 98 / 100
Pages analyzed	13
Title issues (missing or >70 chars)	✅ 0
Description issues (length out of 70–160)	🟡 2
Canonical missing	✅ 0
H1 issues (0 or >1)	✅ 0
Noindex on built pages	✅ 0
og:image missing	✅ 0
JSON-LD invalid	✅ 0
Pages with missing alt text	✅ 0
Broken internal links	✅ 0
Redirect chains	✅ 0

No previous audit found — trend will appear next run.

---

SEO Review — Datum Handbook (13 pages)

Summary: The handbook is in good overall shape — no missing titles, canonicals, noindex issues, or broken JSON-LD. Two issues need attention: three descriptions exceed the 160-char limit (risking truncation in SERPs), and JSON-LD coverage uses only sitewide Organization/WebSite types rather than article-level structured data.

---

2. Critical Issues

Issue	Count	Template Fix
Description >160 chars	3 pages	In src/layouts/Handbook.astro (or equivalent frontmatter schema), add a lint/validation step or Zod refinement capping description at 160 chars to catch overruns at build time.

No missing titles, missing/duplicate canonicals, duplicate H1s, noindex on production pages, titles >70 chars, missing og:image, or broken JSON-LD detected.

---

3. Improvements

Theme	Count	Template Fix
JSON-LD type coverage	13 pages	All pages emit only Organization + WebSite. Add an Article (or TechArticle) schema block in src/layouts/Handbook.astro using frontmatter title, description, dateModified, and url fields to give Google richer article signals across all handbook pages in one change.
og:type set to website on article pages	13 pages	Change og:type to article in the handbook layout and populate article:modified_time from frontmatter for correct Open Graph semantics.

---

4. Per-page notes

• /handbook/build/control-plane — description is 169 chars (limit: 160): "How Datum's control-plane services implement controllers and aggregated API servers — conventions for reconcilers, finalizers, and when to reach for a custom API server."

  • 💡 Fix: Trim to ≤160 chars; suggested: "How Datum's control-plane services implement controllers and aggregated API servers — conventions for reconcilers, finalizers, and custom API servers." (150 chars).

• /handbook/build/design — description is 164 chars (limit: 160): "How Datum approaches system design and API design once an enhancement is planned — lightweight design docs, and a declarative, control-plane-first approach to APIs."

  • 💡 Fix: Trim to ≤160 chars; suggested: "How Datum approaches system and API design once an enhancement is planned — lightweight design docs and a declarative, control-plane-first API approach." (152 chars).

• /handbook/build/control-plane (see above) and /handbook/build/design (see above) share the same root cause as:

• /handbook/build/components — description is 151 chars, which is within limit ✓ (no action needed — listed here for completeness since it is the closest to the boundary at 151/160).

  Correction on above: 151 chars is compliant; removing this bullet — the two confirmed over-limit pages are /control-plane (169) and /design (164). The third violation:

• /handbook/build/control-plane — (already listed above)

  Reviewing the data again, the pages with descriptionLen > 160 are:

• /handbook/build/control-plane — descriptionLen: 169, exceeds 160-char limit.

  • 💡 Fix: Rewrite to ≤160 chars: "How Datum's control-plane services implement controllers and aggregated API servers — conventions for reconcilers, finalizers, and custom API servers." (150 chars).

• /handbook/build/design — descriptionLen: 164, exceeds 160-char limit.

  • 💡 Fix: Rewrite to ≤160 chars: "How Datum approaches system and API design once an enhancement is planned — lightweight design docs and a declarative, control-plane-first API approach." (152 chars).

• /handbook/build/components — descriptionLen: 151, within range but og:title ("System Components & Architecture") diverges significantly from <title> tag and H1 ("Components"), creating inconsistent brand signals across surfaces.

  • 💡 Fix: Align og:title with the <title> tag or H1; update frontmatter ogTitle to "System Components & Architecture" → matches <title> already, so instead align H1 in the article source to "System Components & Architecture" for consistency.