Skip to main content

Build the Docusaurus site's information architecture and give sovdev-logger a real "why OTLP" doc

website/docs/index.md has said since the site was scaffolded that product content is "being migrated in from specification/ and docs/" — that never happened. This plan builds the actual destination (a general//using//contributor/ structure modeled on the sibling mimer project's own Docusaurus site), writes the one explanation doc this project has never had — why sovdev-logger exists and why OTLP specifically, honest about tradeoffs, not just an Azure-framed pitch — shrinks the root README to a mimer-style pitch that points at the site instead of duplicating it, writes down the rule that stops future language READMEs from duplicating content instead of diffing against TypeScript's, and adds a small automated check against the class of doc drift that produced the three-different-GitHub-remotes bug already fixed ahead of this plan. Full migration of specification/'s and docs/'s remaining prose into contributor//using/ is scoped as a follow-up plan once this structure exists — shipped incrementally, the same way mimer's own general/ section went live labeled "Stub" rather than waiting for complete content.

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

Status: Completed​

Completed: 2026-07-08

Addendum (found during PLAN-006): every https://sovdev-logger.sovereignsky.no/... link written in this plan was missing a /docs/ path segment — the docs plugin's route base path was left at the classic-preset default (docs) while docs/index.md's own slug: / clearly intended the site root. Never caught here because fully-qualified URLs aren't checked by Docusaurus's broken-link validator. Fixed in PLAN-006 by setting routeBasePath: '/' (not by patching each link), which makes every link this plan wrote correct without further edits here.

Investigation: INVESTIGATE-documentation-strategy.md — Option C, accepted 2026-07-08, all five open questions decided, destination later redirected to website/docs/ with mimer as the structural model

Goal: website/docs/ has general/, using/, and contributor/ sections (each with an index hub and _category_.json, mirroring mimer's pattern), replacing the placeholder homepage's unfulfilled migration promise. general/ contains the honest, general "why OTLP" doc this project has never had. The root README.md shrinks to a short pitch pointing at the site instead of duplicating it. specification/implementation-guide.md states the diff-against-canonical rule for future language READMEs. A small automated script catches the class of doc drift (inconsistent GitHub remotes, a Supported Languages table that doesn't match reality) found repeatedly by accident in prior plans.

Last Updated: 2026-07-08

Problem​

Confirmed directly (file reads, greps) while researching the investigation this plan implements — see INVESTIGATE-documentation-strategy.md for the full evidence, including the mimer precedent. Summarized here for what this plan specifically acts on:

The Docusaurus site already promises this and never delivered​

website/docs/index.md reads: "This docs site is newly set up — content is being migrated in from the repo's specification/ and docs/ folders. In the meantime, see the project README." website/docs/ today contains only that placeholder and the ai-developer/ process framework — no general/, using/, or contributor/ sections exist yet.

mimer already solves this exact problem, on the same stack​

/Users/tec/learn/helpers/mimer/website/docs/ has general/ (broadest audience, "what this project is, in plain terms"), system/ (architecture-level explanation bridging both audiences, where its "why" and trust content lives), and contributor/ (pure build/maintenance reference) — each with an index.md hub and a _category_.json, using the exact same autogenerated-sidebar convention this repo already uses for website/docs/ai-developer/plans/. mimer's root README is also a ~45-line pitch, not a reference dump — the depth lives on the site.

The root README mixes both audiences and is where the only OTLP rationale currently lives​

## 👥 Choose Your Path (line 85) splits "For Library Users" from "For Language Implementers," but the ~400 lines around it interleave both audiences and marketing content freely, and ## For Microsoft/Azure Developers (150) is the only place any OTLP rationale exists today — Azure-framed, not general. Per [Q5]'s decision, the new general doc must name real costs (more moving parts than a flat logger, a learning curve, dependency on collector infrastructure), not just benefits.

The duplication-vs-diff inconsistency between language READMEs already produced a real bug​

typescript/README.md fully duplicates root-README content; python/README.md diffs against it ("see the TypeScript README's X section"). The duplication side already caused three different GitHub remotes to exist across the three files — fixed ahead of this plan, separately, per [Q3]. Nothing written down yet stops the next language README from repeating TypeScript's pattern instead of Python's.

Phase 1: Build the general//using//contributor/ information architecture​

Tasks​

  • 1.1 Created website/docs/general/, website/docs/using/, website/docs/contributor/, each with an index.md hub and a _category_.json (positions 1/2/3), matching this repo's existing ai-developer/_category_.json format exactly. Bumped ai-developer/_category_.json's position from 2 to 90, mirroring mimer's own choice to rank its process framework below product docs.
  • 1.2 Rewrote website/docs/index.md: replaced the placeholder ("content is being migrated in... In the meantime, see the project README") with a real "About sovdev-logger" hub — what it is, the three-section breakdown with one link each, a note pointing ai-developer/ to process rather than product docs. Also fixed a stale claim caught while rewriting it: the placeholder said "Currently available for TypeScript, with Go, Python, C#, Rust, and PHP planned" — Python has been conformant and available since PLAN-002; corrected.
  • 1.3 general/, using/, and contributor/ all labeled > **Stub.** with a pointer to this plan and, for using//contributor/, to the current authoritative source (the repo's READMEs/specification/) so nothing is a dead end. Deviation from the task as written: general/index.md's own page list (why-otlp.md) also had to be demoted to "Planned pages" rather than a live link — that page lands in Phase 2 of this same plan, not the follow-up plan, but linking to it before it exists broke the build (caught by 1.4's validation, not assumed safe).
  • 1.4 Confirmed sidebars.ts needed no change. Verified in the actual built output (build/docs/index.html), not just assumed: sidebar order is General documentation → Using sovdev-logger → Contributor → ... → AI Developer Workflow, exactly as the _category_.json positions intend.

Validation​

cd website && npm run build

Phase 1: DONE. First attempt failed with two broken links (general/index.md → why-otlp.md, using/index.md → azure-integration.md — both real files Phase 2 creates, not yet present). Fixed by moving both to "Planned pages" text instead of live links. Second build: [SUCCESS] Generated static files in "build", homepage placeholder gone, sidebar order confirmed correct in the built HTML.

Phase 2: Write the "why OTLP" doc into general/​

Tasks​

  • 2.1 Wrote website/docs/general/why-otlp.md: brief pointer back to the root README for the full pitch, then the OTLP case (one wire protocol vs. per-backend integrations, vendor neutrality being structural not policy, local/production parity) and a "What OTLP actually costs" section per [Q5]. The collector-dependency cost isn't hypothetical — it's the exact Transient error... Connection refused text this project's own E2E tests produce without a live collector configured, observed directly multiple times earlier in this session, cited as a concrete example rather than a generic claim.
  • 2.2 Migrated the Azure-specific content into website/docs/using/azure-integration.md: the distro-vs-standard-SDK reasoning and the three-deployment-scenario table (local/in-cluster/Azure, same code, different OTLP endpoint). Deliberately cut the original's quote-dump ("Official Statements," the adoption timeline table) as redundant validation-by-authority rather than load-bearing technical content — the reasoning itself is what's useful, not that Microsoft said it three different ways. The original docs/README-microsoft-opentelemetry.md is now a two-line pointer to both new pages, not a second copy.
  • 2.3 Linked from the root README (a new sentence at the end of the opening pitch, ahead of everything else) and from specification/00-design-principles.md's OpenTelemetry Integration section (a one-line pointer before its existing bullet list, which now explicitly covers "what," leaving "why" to the new doc). Also updated the two existing README references that pointed at the old Azure doc (the "Complete Azure setup guide" link and the Documentation section's link list) to point directly at the new site page instead of through the pointer file.
  • 2.4 why-otlp.md is ~45 lines; azure-integration.md is ~25 — both closer to implementation-guide.md's length than the original 215-line Azure doc.

Validation​

Confirmed against [Q5]'s bar: "What OTLP actually costs" names three concrete costs (more moving parts than console.log, the spans/context-propagation learning curve, live collector dependency), not just benefits. Both cross-links resolve. npm run build → [SUCCESS] Generated static files in "build".

Phase 2: DONE.

Phase 3: Shrink the root README, write the diff-against-canonical rule​

Tasks​

  • 3.1 Cut README.md from 387 to 95 lines: merged "What is sovdev-logger?" with a condensed version of the Problem/Solution pitch and the ops-engineer hook, cut "For Microsoft/Azure Developers" (moved to using/azure-integration.md in Phase 2), "See It In Action," "What You Get Automatically," "Log Structure," "Example: TypeScript," and "Configuration" (all reference/marketing content), merged "Choose Your Path" + "Quick Start" into one tightened Quick Start section covering both audiences without duplication.
  • 3.2 Added one sentence to implementation-guide.md's step 8: new language READMEs diff against typescript/README.md rather than duplicating it, "the way python/README.md does" — linking both as concrete examples, per [Q2].
  • 3.3 Verified, not assumed: every section cut from README.md already exists in full in typescript/README.md (grep-confirmed: "Who Do You Write Logs For?", "The Problem"/"The Solution", "What You Get Automatically", "Log Structure" all present there, unchanged and canonical). Nothing unique was lost — only the redundant copy. Also fixed two stale references caught while editing this exact file: a dangling #example-typescript anchor link (confirmed no longer referenced anywhere after the cut) and specification/README.md's actual version (v2.1.0, bumped in PLAN-003) vs. the README's stale "v2.0.0" claim in Repository Status.

Validation​

Re-read the shrunk README.md top to bottom: a first-time visitor gets what/why/how-to-install in 95 lines, not 387. grep confirmed every cut section survives in typescript/README.md. Re-read implementation-guide.md — grew by one sentence, not a new subsection. npm run build clean.

Phase 3: DONE.

Phase 4: Automated doc-consistency check and final validation​

Tasks​

  • 4.1 Wrote specification/tools/check-doc-consistency.py: checks (a) every github.com/<org>/sovdev-logger reference across README.md, typescript/README.md, python/README.md, docs/*.md matches helpers-no/sovdev-logger; (b) the root README's Supported Languages table's ✅/📅 status matches whether {language}/README.md actually exists on disk, in both directions (catches a stale "Planned" as well as a stale "Available").
  • 4.2 Added to specification/tools/README.md's Quick Reference table.
  • 4.3 Verified both checks actually catch drift, not just always pass: deliberately changed README.md's remote to terchris/sovdev-logger — caught, exact line reported (README.md:75); deliberately flipped Python's table row to "📅 Planned" while python/README.md still exists — caught ("table is stale"). Both restored and re-confirmed clean afterward.
  • 4.4 Full Docusaurus build.

Validation​

python3 specification/tools/check-doc-consistency.py
cd website && npm run build

Phase 4: DONE. OK: GitHub remotes consistent, Supported Languages table matches reality. on the real repo state, confirmed to fail correctly on two independently-introduced scratch mismatches first. npm run build → [SUCCESS] Generated static files in "build".

Acceptance Criteria​

  • website/docs/general/, using/, contributor/ exist with index hubs and _category_.json, replacing the homepage's unfulfilled migration placeholder
  • website/docs/general/why-otlp.md exists, is honest about tradeoffs, and is linked from both the root README and specification/00-design-principles.md
  • The Azure-specific OTLP content has a new home under using/, cross-linked from the general doc, not duplicated
  • The root README is substantially shorter (387 → 95 lines), pointing at the site for depth rather than duplicating it — every removed section verified present in typescript/README.md, nothing silently lost
  • specification/implementation-guide.md states the diff-against-canonical rule in roughly one sentence
  • A doc-consistency check script exists, passes on the current repo, and is verified to actually catch two independently-introduced mismatches
  • website/docs/ builds cleanly after all edits

Files to Modify​

  • website/docs/index.md (rewritten homepage)
  • website/docs/general/, website/docs/using/, website/docs/contributor/ (new — index hubs, _category_.json)
  • website/docs/general/why-otlp.md (new)
  • website/docs/using/azure-integration.md or equivalent (new, migrated from docs/README-microsoft-opentelemetry.md)
  • docs/README-microsoft-opentelemetry.md (left as a pointer to its new home)
  • README.md (shrunk to a pitch, link to the site)
  • specification/00-design-principles.md (link to the new doc)
  • specification/implementation-guide.md (one-sentence diff-against-canonical rule)
  • specification/tools/ (new doc-consistency check script)
  • specification/tools/README.md (tool reference entry)

Explicitly out of scope for this plan (follow-up plan, per the investigation's Recommendation): migrating typescript/README.md/python/README.md's quickstart content into using/, migrating specification/00-design-principles.md through 10-code-quality.md and implementation-guide.md into contributor/, and migrating the remaining docs/*.md files (configuration, logging concepts, observability architecture, Loggeloven) into using/.