Spec Writing Discipline
Spec writing discipline is the organizational practice of treating product writing as a load-bearing skill — not a checkbox. The discipline sits between three artifacts: the PRD (what we're building and why), the engineering design doc (how we'll build it), and the decision log (what we decided and what we considered). Companies known for product writing — Stripe, Amazon, Basecamp, GitLab — share four habits: (1) writing precedes meetings, not the other way around; (2) specs are short and prose-heavy, not bullet-heavy; (3) every spec names what's IN scope and what's NOT; (4) specs are versioned and findable months later. Spec discipline is the difference between an org that thinks before building and one that builds, then writes the spec to match the code.
The Trap
The trap is performing spec discipline without internalizing it: PMs who write 12-page documents that nobody reads, decorated with diagrams and 'comprehensive' edge case enumeration. The output looks rigorous but produces no clearer thinking. The opposite trap is the verbal-first culture: 'we'll discuss it in the meeting' — which works for a 5-person team and collapses at 25, when no two people remember the same decision. The deepest trap is 'spec theater': writing the document AFTER the decision is already made, then circulating it for ceremonial sign-off. Real spec discipline means the written draft changes the decision at least 30% of the time.
What to Do
Install four practices: (1) Write a one-pager BEFORE the kickoff meeting and circulate it 24 hours ahead — meetings start with silent reading, not status. (2) Cap PRDs at 3 pages; if it's longer, you haven't decided what's important. (3) Require a 'non-goals' section in every spec, with at least 3 items. (4) Maintain a decision log (separate concept) of every spec-level decision, what was considered, and why the chosen path won. Audit quarterly: if specs from 6 months ago are unreadable, untraceable, or contradicted by the code, the discipline isn't working.
In Practice
GitLab's all-remote handbook (over 2,500 pages, fully public) is the most extreme published example of spec writing discipline at scale. Every product decision, process, and rationale is written down — making the company functionally async-first. CEO Sid Sijbrandij has cited the handbook as the reason GitLab can hire globally without onboarding overhead. The discipline isn't about the page count; it's about the rule: 'if it's not written, it doesn't exist.' That rule eliminates the institutional memory loss that hits most companies once they cross 100 employees. (Source: GitLab Handbook, public)
Pro Tips
- 01
Patrick Collison (Stripe CEO) has publicly argued that writing quality directly correlates with engineering velocity: clear specs reduce back-and-forth, hidden assumptions, and rework. Stripe's API documentation is the visible artifact of an internal writing culture that treats prose as engineering output.
- 02
Use the 'first paragraph test': if the opening paragraph of your spec doesn't make a non-expert reader say 'oh, I get it,' rewrite it before circulating. The first paragraph IS the spec — everything else is supporting detail.
- 03
Ban 'TBD' from final specs. Every TBD is a deferred decision that will become an unresolved argument during build. Either decide now, list it as an explicit open question with an owner and a deadline, or scope it out as a non-goal.
Myth vs Reality
Myth
“Writing is a soft skill — engineering teams don't need it”
Reality
Engineering teams with bad spec discipline ship more code that gets thrown away. The cost of a 4-week build that misses the requirement is 1000x the cost of a 2-day spec rewrite. Writing IS the requirements engineering. Companies treating it as soft skill are paying the cost in re-work they don't measure.
Myth
“Async writing slows companies down — meetings are faster”
Reality
Meetings feel faster because the cost is hidden. A 1-hour meeting of 8 people is 8 hours of company time + the rework cost when half of them later remember different decisions. A 30-minute spec read that everyone does at their own pace, plus 30 minutes of focused discussion, is dramatically less expensive AND produces a written record. GitLab, Basecamp, and Automattic operate at scale this way.
Try it
Run the numbers.
Pressure-test the concept against your own knowledge — answer the challenge or try the live scenario.
Scenario Challenge
A founder-CEO at your 80-person company says 'we don't have time for long PRDs — let's just sync up in standup and decide things faster.' Six months later, two engineering teams shipped overlapping features and a sales rep promised a customer something the product can't do.
Industry benchmarks
Is your number good?
Calibrate against real-world tiers. Use these ranges as targets — not absolutes.
Spec Writing Investment per Major Project
Mid-stage and growth-stage product orgsHigh Discipline (Stripe, Amazon, GitLab pattern)
2-4 hours of writing per project
Healthy
1-2 hours
Light
<30 min — slack message + ticket
None
Verbal-only decisions
Source: Stripe, Amazon, GitLab public practice
Real-world cases
Companies that lived this.
Verified narratives with the numbers that prove (or break) the concept.
GitLab Handbook
2014-present
GitLab built the world's largest publicly visible handbook (2,500+ pages) as the operational substrate for an all-remote, async-first company. The rule is 'handbook-first': if a process or decision isn't in the handbook, it doesn't exist. This forced every team to write things down — including product specs, decision rationale, hiring rubrics, and incident runbooks. The discipline let GitLab scale past 1,500 employees across 60+ countries without the in-person onboarding most companies depend on. CEO Sid Sijbrandij has called the handbook the company's most important asset.
Handbook Length
2,500+ pages
Visibility
Fully public
Operating Model
All-remote, async-first
Onboarding Pattern
Handbook-driven, no in-person required
Spec writing discipline scales companies that would otherwise hit institutional memory bottlenecks at 100-200 employees. The handbook isn't bureaucracy — it's the company's working memory.
Amazon — Memo Culture
~2004-present
Amazon's shift from PowerPoint to 6-page narrative memos (driven by Jeff Bezos in the early 2000s) restructured how the company makes product decisions. Meetings start with 20-30 minutes of silent reading; debate happens after everyone has the same context. Bezos has publicly attributed the format with surfacing weak thinking that bullet-points hide. The PR/FAQ extension — writing a press release for the product BEFORE building it — forces teams to articulate the customer benefit in their own marketing language before committing engineering capacity.
Standard Format
6-page narrative + PR/FAQ
Meeting Pattern
Silent read first
PowerPoint Use
Banned for major decisions
Adoption
Standard across Amazon
The format an org uses for spec writing shapes its decision quality. Prose forces thinking; bullets allow hand-waving. Amazon's memo culture is one of the highest-leverage organizational design choices the company ever made.
Related concepts
Keep connecting.
The concepts that orbit this one — each one sharpens the others.
Beyond the concept
Turn Spec Writing Discipline into a live operating decision.
Use this concept as the framing layer, then move into a diagnostic if it maps directly to a current bottleneck.
Typical response time: 24h · No retainer required
Turn Spec Writing Discipline into a live operating decision.
Use Spec Writing Discipline as the framing layer, then move into diagnostics or advisory if this maps directly to a current business bottleneck.