Headless Websites and the Cost of Engineering Vanity  🔗 **Source:** [Headless Websites and the Cost of Engineering Vanity](https://www.jonoalderson.com/conjecture/headless-websites/) > [!note]+ Document Notes > tags: #headless-cms #web-development #marketing-websites #engineering #developer-experience > author: Jono Alderson > source: jonoalderson.com > reference: https://www.jonoalderson.com/conjecture/headless-websites/ > date created: 2024-12-28 16:32 > > # 🏷️ Title: Headless websites and the cost of engineering vanity > <!-- deep-read:sections start --> ## 🧰 Action Inbox - [H1] Audit current website architecture against actual marketing needs — evaluate if headless complexity serves business goals #web-development - [H2] Review team capabilities for maintaining custom platform solutions — assess engineering depth vs operational requirements #team-management - [H3] Document real flexibility requirements vs theoretical possibilities — distinguish between what marketers need vs what engineers want to build #requirements-analysis ## 🧭 Table of Contents - [[#📝 Summary]] - [[#📖 Main Content]] - [[#🗒️ Notes]] - [[#📚 References]] - [[#🗣️ Paraphrase]] - [[#📰 Newsletter]] - [[#✅ Action Items]] - [[#🧪 Hypotheses]] - [[#📊 Methodology]] - [[#❓ Questions]] - [[#🔮 Future Research]] - [[#💡 Implications]] - [[#🧠 Learning Styles Assessment]] - [[#📊 Accessibility Assessment]] - [[#🌍 DEIB Assessment]] - [[#✅ Logical Validity]] - [[#🛡️ DARVO Analysis]] - [[#🎯 Conclusion]] ### 🔗 References - [Headless websites and the cost of engineering vanity](https://www.jonoalderson.com/conjecture/headless-websites/) ## 📝 Summary - **What happened**: Jono Alderson argues that headless website architectures are often chosen for engineering vanity rather than business needs, creating complexity that harms marketing operations - **Why it matters**: Most marketing websites don't need headless complexity, and the architecture often reduces operational flexibility while claiming to increase technical flexibility - **Key stakeholders**: Marketing teams who lose publishing autonomy, engineering teams pursuing technical ideals, businesses paying for unnecessary complexity - **Risks and tradeoffs**: Headless promises flexibility but often delivers dependency, complexity, and reduced marketing agility - **Bottom line takeaway**: For most marketing websites, a well-built traditional architecture serves business needs better than headless complexity ## 📖 Main Content Alderson challenges the assumption that headless architectures are inherently superior for marketing websites. He argues that while headless can deliver benefits like flexibility, performance, and security, these same benefits are achievable with simpler architectures that don't require rebuilding web platform fundamentals. The core issue is a mismatch between engineering priorities and business needs. Engineers value architectural purity and technical control, while marketers need operational speed and publishing autonomy. Headless often optimizes for the former at the expense of the latter. The article identifies several problematic patterns: teams rebuilding solved problems instead of leveraging web platform defaults, complexity justified by theoretical future needs rather than current requirements, and architectural decisions that shift power from content teams to engineering teams. Alderson acknowledges that headless can be appropriate for genuinely complex multi-channel publishing requirements, but argues this represents a small minority of actual use cases. Most marketing websites benefit more from well-implemented traditional architectures than bespoke headless solutions. ## 🗒️ Notes #### ⏱️ Article Introduction — [H1] Headless promises vs reality - Key idea: Headless is sold as flexibility but often delivers new constraints disguised as sophistication - Evidence: "Headless sounds like a route to freedom, but too often it just swaps one set of constraints for another, heavier one" #### ⏱️ Section 1 — [H2] Marketing websites aren't engineering playgrounds - Key idea: Websites derive value from marketing usefulness, not architectural elegance - Evidence: "Can they actually do marketing?" - the fundamental test for marketing website architecture #### ⏱️ Section 1 Continued — [H3] System flexibility vs operational flexibility - Key idea: Theoretical system capabilities don't equal practical marketing agility - Evidence: "A system that can theoretically render any kind of page is not very flexible if producing one requires developer intervention" #### ⏱️ Section 2 — [H2] Performance and security don't require headless - Key idea: Common headless benefits are achievable with simpler architectures - Evidence: "Fast websites come from making sensible decisions about payloads, rendering, caching, assets, infrastructure, and complexity" #### ⏱️ Section 2 Continued — [H3] Security through governance not architecture - Key idea: Practical security comes from operational discipline, not decoupling - Evidence: "A tightly managed conventional stack can be extremely secure. A badly governed headless stack can be a sprawling mess" #### ⏱️ Section 3 — [H1] Rebuilding web platform capabilities - Key idea: Headless teams volunteer to reimplement browser and web platform features - Evidence: "Once you take responsibility for all of that, you also take responsibility for all the failure modes" #### ⏱️ Section 3 Continued — [H3] Loss of helpful defaults - Key idea: Traditional web stacks provide valuable constraints and conventions - Evidence: "Good defaults are one of the most undervalued features of the traditional web stack" #### ⏱️ Section 4 — [H2] Most teams lack required expertise - Key idea: Headless requires broad, deep expertise most teams don't possess - Evidence: "To build a headless marketing website well, you need a team that understands rendering strategies, caching, content modelling, preview workflows..." #### ⏱️ Section 4 Continued — [H3] Compromises under time pressure - Key idea: Real-world delivery pressure leads to shortcuts that undermine headless benefits - Evidence: "Projects have deadlines. Stakeholders want features... So compromises pile up" #### ⏱️ Section 5 — [H3] Capability isn't strategy - Key idea: Ability to build something doesn't justify building it - Evidence: "The fact that a team can build something does not mean that building it is a good use of time, money, attention, or organisational energy" #### ⏱️ Section 5 Continued — [H2] Opportunity cost of rebuilding - Key idea: Time spent recreating existing capabilities isn't spent improving business effectiveness - Evidence: "Every hour spent rebuilding those things is an hour not spent improving the actual effectiveness of the website" #### ⏱️ Section 6 — [H1] Marketers bear the consequences - Key idea: Architecture decisions by engineers create operational friction for marketing teams - Evidence: "The architecture is sold as flexibility, but the lived experience is often reduced agency" #### ⏱️ Section 7 — [H2] When headless is justified - Key idea: Headless makes sense when complexity is inherent to business needs, not introduced by architecture - Evidence: "Headless is justified when the complexity is already inherent in the business, not when the architecture introduces complexity" #### ⏱️ Section 8 — [H1] The better default: normal websites done well - Key idea: Well-built traditional websites serve most marketing needs better than headless complexity - Evidence: "For most organisations, the right answer is not a headless website. It is a normal website, built properly" ## 📚 References - [Headless websites and the cost of engineering vanity](https://www.jonoalderson.com/conjecture/headless-websites/) - [Jono Alderson's website](https://www.jonoalderson.com/) ## 🗣️ Paraphrase - Headless architectures are often chosen to satisfy engineering preferences rather than business requirements, creating unnecessary complexity for marketing websites - The benefits commonly attributed to headless (flexibility, performance, security) are achievable with traditional architectures that don't require rebuilding web platform fundamentals - Marketing teams lose operational autonomy when websites become bespoke engineering projects that require developer intervention for routine publishing tasks ## 📰 Newsletter **Stop Building Engineering Monuments, Start Serving Marketing Teams** This week's essential read challenges a growing trend in WordPress and web development: the rush toward headless architectures. Jono Alderson's deep dive reveals why most marketing websites benefit more from well-implemented traditional stacks than complex decoupled systems. **Key insight**: "Engineering flexibility" often reduces "marketing flexibility." When developers gain architectural control, content teams frequently lose publishing autonomy. **Practical application**: Before choosing headless, audit your actual requirements. Do you need multi-channel content syndication, or do you just want a fast, flexible marketing site? Most teams need the latter, which traditional WordPress setups handle excellently. **WordPress connection**: This directly applies to headless WordPress implementations. While WordPress as a headless CMS can work for complex use cases, most sites benefit more from modern WordPress themes with proper caching, performance optimization, and editorial workflows. Resources: [WordPress Performance Guide](https://make.wordpress.org/core/handbook/best-practices/performance/), [Block Editor Documentation](https://developer.wordpress.org/block-editor/), [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) ## ✅ Action Items #### DevRel - Developer education: Create content comparing headless vs traditional architectures with real business impact metrics - Documentation: Develop decision frameworks for architecture choices based on actual requirements vs engineering preferences - Community engagement: Host discussions about balancing technical ideals with operational practicality - Developer experience: Document when complexity is justified vs when simplicity serves users better #### WordPress - Core: Ensure block editor and site editing continue improving traditional WordPress flexibility without requiring headless complexity - Documentation: Create clear guidance on when headless WordPress makes sense vs when traditional themes suffice - Performance: Demonstrate that traditional WordPress can achieve excellent performance with proper optimization - Community: Address misconceptions about WordPress flexibility and modern development practices - Training: Develop curriculum helping developers evaluate architecture decisions against business outcomes - Themes: Promote best practices for flexible, maintainable theme development that serves marketing needs #### Community - Education: Share case studies showing successful marketing websites built with traditional architectures - Mentorship: Guide teams through architecture decisions based on actual requirements rather than industry trends - Documentation: Create resources helping marketing teams communicate their needs to engineering teams ## 🧪 Hypotheses - Teams choosing headless for marketing websites experience decreased content publishing velocity compared to well-implemented traditional stacks - Organizations with headless marketing sites require higher engineering maintenance costs without proportional business benefits - Marketing team satisfaction correlates negatively with website architectural complexity when complexity exceeds business requirements - Traditional WordPress sites with modern optimization techniques achieve comparable performance to headless implementations for typical marketing use cases ### 📊 Methodology - Survey marketing teams about publishing workflow satisfaction across different architecture types - Compare time-to-publish metrics between headless and traditional marketing websites - Analyze total cost of ownership including development, maintenance, and operational overhead - Benchmark performance metrics across architecture types with equivalent optimization effort ### ❓ Questions - How can we better align engineering architectural preferences with marketing operational needs? - What specific business requirements genuinely justify the complexity trade-offs of headless architecture? - How do we measure and communicate the opportunity cost of rebuilding vs leveraging existing web platform capabilities? ### 🔮 Future Research - Develop frameworks for evaluating architecture decisions against business impact rather than technical elegance - Study long-term maintenance burden differences between headless and traditional marketing websites - Investigate correlation between architectural complexity and team velocity in content organizations ### 💡 Implications - **Practice**: Teams should start with business requirements rather than architectural preferences when choosing website technology - **Policy**: Organizations need governance frameworks that prevent engineering decisions from undermining marketing effectiveness - **Education**: Developer training should emphasize serving business needs rather than pursuing technical ideals - **Funding**: Budget allocation for website projects should account for ongoing operational complexity, not just initial development costs ### 🧠 Learning Styles Assessment Reading level estimate: Grade 12-14 (sophisticated business and technical content) #### 👀 Visual learners - Present: Clear section headings, structured arguments, conceptual frameworks - Improve: Diagrams comparing traditional vs headless architectures, flowcharts showing decision processes, visual cost-benefit comparisons #### 🔊 Aural learners - Present: Strong narrative flow, conversational tone, logical argument progression - Improve: Audio version highlighting key decision points and practical implications #### 🗣️ Verbal learners - Present: Rich analogies, clear definitions, business terminology explained - Improve: Glossary of technical terms, more concrete examples of architectural impacts #### 🧩 Kinesthetic learners - Present: Practical examples, actionable insights, real-world scenarios - Improve: Checklists for architecture evaluation, hands-on exercises comparing approaches #### 🧠 Logical learners - Present: Clear cause-effect relationships, systematic argument structure, evidence-based reasoning - Improve: Decision matrices, quantitative comparisons, logical flowcharts #### 🧑‍🤝‍🧑 Social learners - Present: Multiple stakeholder perspectives, team dynamics considerations - Improve: Discussion guides for cross-functional architecture decisions, collaborative evaluation frameworks #### 🧘‍♀️ Solitary learners - Present: Comprehensive analysis, independent reasoning opportunities - Improve: Self-assessment tools for architecture decisions, reflection questions #### 🌿 Naturalistic learners - Present: Systems thinking, ecosystem considerations - Improve: Analogies to natural systems, lifecycle thinking about architecture evolution ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Clear heading hierarchy, logical document structure - Improve: More descriptive section headings, better landmark navigation #### Keyboard navigation - Present: Standard web navigation patterns - Improve: Skip links for long-form content, section jumping capabilities #### Contrast and readability - Present: Clean typography, good contrast ratios - Improve: Ensure all text meets WCAG AA standards, test with various color vision needs #### Text resizing and reflow - Present: Responsive design, scalable text - Improve: Test at 200% zoom, ensure no horizontal scrolling #### Media and captions - Present: Text-based content primarily - Improve: Alt text for any diagrams or visual elements added #### Forms and interactions - Present: Minimal interactive elements - Improve: Ensure any forms meet accessibility standards ### 🌍 DEIB Assessment #### Cultural breadth - Present: Business-focused perspective applicable across regions - Improve: Examples from diverse organizational types and geographic contexts #### Inclusive language - Present: Professional, clear communication without unnecessary jargon - Improve: Plain language summaries, avoid assumptions about organizational structure #### Neurodiversity support - Present: Well-structured content with clear sections - Improve: Better visual hierarchy, shorter paragraphs, bullet point summaries #### Representation - Present: Focus on business outcomes rather than individual personalities - Improve: Include diverse organizational examples, avoid defaulting to specific company types #### Psychological safety - Present: Respectful critique of technical approaches without attacking individuals - Improve: Emphasize learning and improvement rather than judgment ### ✅ Logical Validity #### Strong reasoning - Deductive strength: Strong logical progression from premises about business needs to conclusions about architecture choices - Inductive strength: Good use of patterns observed across multiple projects to form general principles - Causal reasoning: Clear cause-effect relationships between architectural decisions and business outcomes - Analogical strength: Effective analogies comparing website architecture to other engineering decisions #### Fallacies - Potential false dichotomy: Presents headless vs traditional as binary choice, though hybrid approaches exist - Appeal to consequences: Some arguments focus heavily on negative outcomes without fully acknowledging successful headless implementations #### Tone of voice - Overall tone: Authoritative but not dogmatic, critical but constructive, uses concrete examples and avoids purely theoretical arguments ### 🛡️ DARVO Analysis - Deny: No significant denial patterns detected - Attack: Critiques ideas and approaches rather than individuals - Reverse victim/offender: No victim/offender reversal patterns - Emotional cues and rhetoric: Uses measured criticism focused on outcomes rather than personal attacks ## 🎯 Conclusion Alderson makes a compelling case that headless architectures are often chosen for engineering satisfaction rather than business necessity. The core insight is that architectural sophistication should serve operational effectiveness, not override it. For most marketing websites, well-implemented traditional approaches provide better business outcomes than bespoke headless solutions. The practical takeaway for teams is to start with business requirements rather than architectural preferences. Ask whether your website needs genuine multi-channel complexity or just fast, flexible publishing. Most marketing sites need the latter, which traditional stacks handle excellently when implemented properly. This connects to broader questions about technology decision-making: How do we balance engineering ideals with business practicality? How do we resist the temptation to over-engineer solutions to problems that don't exist? The best architecture is often the simplest one that satisfies actual requirements. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad ### [H1] Marketing websites prioritize operational speed over architectural purity > [!quote] [Headless websites and the cost of engineering vanity](https://www.jonoalderson.com/conjecture/headless-websites/) by Jono <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Articles/Headless Websites and the Cost of Engineering Vanity.md|Headless Websites and the Cost of Engineering Vanity by jonoalderson.com]] ## Highlights - But most websites do not fail because they lacked architectural purity. They fail because they are hard to update, slow to evolve, politically constrained, badly governed, and disconnected from the people trying to use them to do actual marketing. Headless does not solve those problems by default. Quite often, it makes them worse. ([View Highlight](https://read.readwise.io/read/01kp8jhram5fyk148rvhg56ycx)) - Tags: 👻 ai highlighted - And then there is the quiet sleight of hand at the heart of the pitch. The argument is usually not just that headless can deliver these benefits, but that it is the best, or only, serious way to achieve them. That is where the logic falls apart. You do not need a headless architecture to build a fast website. You do not need one to build a secure platform. You do not need one to create flexible templates, structured content, or sane workflows. Those are all achievable within far simpler systems, with far fewer moving parts, and far less opportunity for a team to disappear into a months-long exercise in bespoke platform engineering. ([View Highlight](https://read.readwise.io/read/01kp8jhrav9y99wp7pm3qvv5nz)) - Tags: 👻 ai highlighted - In fact, the irony is that many headless builds end up slower precisely because the team has mistaken architectural modernity for optimisation. They ship a JavaScript-heavy front end, layer in preview tooling, bolt on personalisation, add client-side search, and slowly recreate all the weight and fragility they thought they were escaping. The result is often a site that demos well in a greenfield prototype and degrades rapidly once real-world requirements start piling up. ([View Highlight](https://read.readwise.io/read/01kp8jhrbxkbsyvtpsm9vpxc2w)) - Tags: 👻 ai highlighted - This is one of the reasons headless projects so often compromise SEO, performance, and accessibility without meaning to. Not because anybody set out to make those things worse, but because once the system stops being a document-first website and starts being a custom-rendered product, all the easy assumptions disappear. Every detail has to be chosen deliberately. Every capability has to be protected on purpose. Every omission becomes technical debt. ([View Highlight](https://read.readwise.io/read/01kp8jhrdqmn9kb13p1gk0rscm)) - Tags: 👻 ai highlighted - This is also why so many headless projects end up depending on a handful of key people. Once the architecture becomes bespoke, institutional knowledge gets trapped inside the team that built it. Marketers do not understand how it works. New developers take time to get productive. Agencies leave behind undocumented patterns. The whole platform becomes harder to reason about, harder to govern, and harder to change safely. The site may have been sold as more flexible, but in practice it has become more dependent on specialist knowledge. ([View Highlight](https://read.readwise.io/read/01kp8jhrfrvkfqbmcyat78432p)) - Tags: 👻 ai highlighted - That is the bit teams consistently underplay. The real cost of headless is not only in infrastructure or maintenance. It is in distraction. Attention gets pulled into platform concerns. Roadmaps fill up with engineering work whose main purpose is to achieve parity with what a more conventional system would have provided from the outset. Delivery slows. Marketing waits. Campaigns get shaped around system constraints. Small changes start needing estimation. Easy wins disappear into backlog grooming. The website becomes a programme of work rather than a tool for getting work done. ([View Highlight](https://read.readwise.io/read/01kp8jhrj9r5anqa5tngjj1kq4)) - Tags: 👻 ai highlighted - This is partly because headless systems tend to encode decisions more rigidly than teams expect. In order to make a decoupled platform manageable, you end up defining components, schemas, rules, and editorial boundaries with increasing precision. Again, none of that is inherently bad. Some structure is healthy. But the more the system depends on custom logic and developer-owned abstractions, the more ordinary marketing activity gets funnelled through the assumptions of the people who built it. The result is a website that is technically modular but operationally inflexible. ([View Highlight](https://read.readwise.io/read/01kp8jhrndbnayh291gndcjs7e)) - Tags: 👻 ai highlighted - There are organisations for whom it is a sensible choice. There are teams with the engineering depth, editorial discipline, governance maturity, and operational patience to make it work. There are products and publishing models whose needs genuinely extend beyond what a more conventional website stack can comfortably support. The problem is not that headless never makes sense. The problem is that it is treated as an aspirational default when it should be a narrow exception. ([View Highlight](https://read.readwise.io/read/01kp8jhrs86bne0gj410j0q06x)) - Tags: 👻 ai highlighted - And that, really, is the whole case against headless as a default. Not that it cannot work. Not that it never has value. But that most organisations do not need a website architecture built around exceptional requirements, exceptional talent, and exceptional discipline. They need a website that works. One that can publish quickly, evolve safely, perform well, rank well, and support the people responsible for growth. ([View Highlight](https://read.readwise.io/read/01kp8jhryjvpxma6eh728erw9s)) - Tags: 👻 ai highlighted