Skip to content

Commit e80e19c

Browse files
brabojclaude
andauthored
docs: add ADR-007 (analytics tooling) and ADR-008 (playbook split rule) (#181)
Two decisions from the 2026-04-25 audit session that were recorded in the dev journal but not as formal ADRs. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bdffd32 commit e80e19c

2 files changed

Lines changed: 62 additions & 0 deletions

File tree

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

0 commit comments

Comments
 (0)