How do I write a technical design doc the team will actually read?
Frame the doc as a discussion organised toward a decision: problem and non-goals up top, rejected alternatives visible, and an explicit approval asked for.
Just Ask
Ask me anything about software architecture, careers, PHP, Go and the craft of building software; I answer here, in the open, for everyone.
Whatever’s on your mind, don’t hold back. Questions reach me directly; I answer the good ones and publish them on this page. Your email is never published.
The questions here are compiled from what I have run into in the field and from what people have asked me; I write the answers. No record carries the name of whoever asked.
Frame the doc as a discussion organised toward a decision: problem and non-goals up top, rejected alternatives visible, and an explicit approval asked for.
Page on symptoms the user feels, like latency and error rate, and move CPU and memory to dashboards and tickets except predictive saturation.
Bundle both architectures under one buildx tag, cross-compile Go with TARGETARCH, and use native arm64 runners when extension builds drag under QEMU.
Default to Merge Patch with ETag/If-Match, and switch specific endpoints to JSON Patch only for element-level array edits or conditional multi-field ops.
Route a user's reads to the primary for a few seconds after their write, and reach for LSN fencing only if that window isn't precise enough.
Start with singleflight plus stale-while-revalidate, and add a Redis distributed lock only once per-pod rebuilds measurably hurt Postgres.
Keep query rules in local scopes and test them against a real database; add a repository only when the domain genuinely has to decouple from Eloquent.
Read attributes once per class into a cached mapping plan rather than per request, and compile to generated PHP only if the profile still shows reflection.
Fix the easy 90% of the comments silently, batch the genuine disagreements into one short call, and never reply the same day you read them.
Keep unbounded labels like user_id off your metrics, restrict labels to bounded dimensions, and take per-customer breakdowns to exemplars or traces.