diff --git a/docs/decisions/007-analytics-tooling.md b/docs/decisions/007-analytics-tooling.md new file mode 100644 index 0000000..e73d0ef --- /dev/null +++ b/docs/decisions/007-analytics-tooling.md @@ -0,0 +1,30 @@ +# ADR-007: Analytics tooling — GSC for tutorials, Plausible for Wuseria + +**Status:** Accepted +**Date:** 2026-04-25 + +## Context +The tutorial site needed analytics to measure search performance and reader +engagement. The options ranged from free (Google Search Console, Google +Analytics) to privacy-focused paid tools (Plausible, Fathom). + +## Decision +Use Google Search Console (GSC) for all Code with Branko tutorials. Reserve +Plausible for commercial products (Wuseria) where privacy-first analytics +justify the cost. + +## Alternatives considered +- **Google Analytics**: Free and full-featured, but heavy JavaScript bundle, + cookie banners required, and privacy concerns for a developer audience +- **Plausible for everything**: Clean and privacy-first, but costs money per + site — unnecessary for free tutorials where GSC covers the key metrics + (impressions, clicks, indexing) +- **No analytics**: Leaves content decisions ungrounded — no way to know + which chapters attract readers or which queries drive traffic + +## Consequences +- GSC is free and sufficient for tutorials — covers search performance, + indexing, and sitemap validation +- No client-side analytics script on tutorial pages — faster load, no + cookie banner +- Plausible cost is only incurred for commercial products diff --git a/docs/decisions/008-playbook-split-rule.md b/docs/decisions/008-playbook-split-rule.md new file mode 100644 index 0000000..dc22d08 --- /dev/null +++ b/docs/decisions/008-playbook-split-rule.md @@ -0,0 +1,32 @@ +# ADR-008: Playbook split rule — standalone pages for substantial recipes + +**Status:** Accepted +**Date:** 2026-04-25 + +## Context +The playbook chapter was split from a single file into individual recipe +pages for SEO (#129, #153). The question was which recipes justify their +own page versus staying grouped in a parent file. + +## Decision +A recipe gets its own page only if it has enough substance to stand alone — +at minimum a command, an explanation, and a gotcha or variation. One-liner +recipes stay grouped in their parent file. + +## Alternatives considered +- **Every recipe gets its own page**: Maximises long-tail SEO surface, but + creates thin pages that dilute quality signals and fragment navigation +- **Keep everything grouped**: Simpler structure, but long pages rank poorly + for focused queries like "how to remove a git submodule" +- **Split by search volume**: Data-driven but requires keyword research + tooling and ongoing maintenance — too heavy for a one-person operation + +## Consequences +- Recipes with multi-step workflows, scripts, or common gotchas become + standalone pages (e.g. git bisect, pre-commit hook, SSH setup, remove + submodule) +- Simple one-liner recipes stay grouped in their parent topic file +- The rule is content-driven, not data-driven — no dependency on keyword + tools +- Issue #154 (improve thin recipes) should run before #153 (split into + pages) to ensure substance exists before splitting