Making Better Technical Decisions: A Simple Framework That Works
In software development, technical decisions are everywhere—and they’re rarely black and white.
Should we build a Single Page Application (SPA) or go with a traditional Multi Page Application (MPA)?
Should we adopt Kubernetes or stick to a simpler platform-as-a-service solution?
Should we build in-house or integrate with a third-party tool?
These are decisions that can affect architecture, team productivity, security, and even long-term costs. And yet—many of them are made casually.
We often default to what we’re most familiar with. We choose technologies we’ve used before. We chase trends. We follow hunches.
And while that might work for small-scale projects or quick experiments, it doesn’t scale well in complex, real-world environments where constraints are real, trade-offs are painful, and alignment across teams is essential.
So how do we avoid decision fatigue, avoid groupthink, and make thoughtful, transparent, and context-aware choices?
Let me introduce you to a simple but powerful tool:
🧠 The Technical Strategy Document (TSD)
A Technical Strategy Document, or TSD, is a lightweight framework for evaluating and documenting important technical decisions. Think of it as the engineering equivalent of a decision log—an intentional pause to ask:
What problem are we trying to solve?
What constraints or principles do we need to honor?
What are the realistic paths forward?
Which one fits our context the best—and why?
This is not about over-engineering your process or adding unnecessary bureaucracy.
In fact, most TSDs can be created in under an hour.
It’s about making thinking visible—so that current and future team members can understand not just what was decided, but why it was the right decision at the time.
📝 The TSD Template
Here’s the simple template I use when writing a Technical Strategy Document. It can be adapted to your team’s needs or product context, but the structure has held up well across a range of decisions—from frontend architecture to cloud infrastructure to API design.
1. Questions This Document Should Answer
What is the key decision being made? What are the big unknowns or trade-offs we're trying to resolve?
2. Area Description
Provide a concise description of the problem area—what system or workflow is affected, and why this decision is needed now. Include links to relevant specs or pre-read material if needed.
3. Decision Criteria
What principles, constraints, or non-negotiables must guide this decision? These could be technical (e.g., performance, security, scalability), business-related (e.g., cost, licensing), or team-specific (e.g., skills, velocity).
4. Decision Summary
In 1–2 sentences, what are we proposing to do? This is the headline—the recommendation without all the nuance (which comes next).
5. Primary Options Considered
Outline the realistic options that were on the table, and summarize their strengths and weaknesses.
6. Decision Details and Reasoning
Explain why the chosen option makes the most sense in the current context. If useful, include a comparison table showing how each option stacks up against the decision criteria.
7. Open Issues and Questions
What remains unresolved? What needs further experimentation, validation, or input?
8. Links to Relevant Documentation
Include links to product specs, meeting notes, architecture diagrams, or other supporting materials.
9. Appendix: Other Options Observed and Discarded
Mention ideas that were discussed briefly but eliminated early in the process. This helps avoid rehashing old ground in the future.
🎯 A Practical Example: SPA vs MPA for a Customer Dashboard
Let’s apply this template to a real-world decision: choosing between a Single Page Application (SPA) and a Multi Page Application (MPA) for a customer-facing dashboard.
Many teams default to building SPAs simply because they’re familiar with React or Angular. But that might not always be the best fit—especially when SEO, performance, or security are concerns.
Here’s how we’d evaluate this choice with a TSD:
Title: Choosing Between SPA and MPA for Customer Dashboard
Author: Vaibhav
Date: March 22, 2025
Questions This Document Should Answer
Should the dashboard be built as an SPA or MPA?
Which option offers the right balance of SEO, performance, user experience, and developer productivity?
Area Description
We’re building a new customer-facing dashboard for our SaaS product. It will include authenticated pages like usage analytics, billing history, profile settings, and help documentation.
The dashboard must be mobile-responsive, SEO-friendly (for help content), performant even on slower networks, and secure. Our frontend team is proficient in React.
Decision Criteria
Initial load performance on low bandwidth
SEO-friendliness for public help content
Developer velocity and team familiarity
Security best practices (especially around authentication and cross-site scripting)
User experience, including fast transitions and responsiveness
Maintainability and future scalability
Decision Summary
We will use Next.js, a hybrid framework that supports both server-side rendering (SSR) and client-side interactivity. Public pages like help articles will be server-rendered for SEO. Authenticated dashboard views will use client-side rendering for a fast, app-like experience.
Primary Options Considered
SPA with React + React Router
✅ Great developer experience and interactivity
🚫 Poor SEO without extra setup
🚫 Slower initial load on weaker networksTraditional MPA with server-rendered templates (e.g., Rails, Django)
✅ Secure and SEO-friendly by default
🚫 Not as interactive or modern
🚫 Slower iteration for frontend teamsHybrid approach using Next.js (SSR + CSR)
✅ Strong SEO and performance
✅ Familiar to React developers
✅ Flexible and future-proof
Decision Details and Reasoning
Open Issues and Questions
How will we handle secure authentication across SSR and CSR pages?
Are there any constraints around server-side rendering in our hosting setup?
Do we need to preload any dashboard data during SSR?
Links to Supporting Documentation
<Customer Dashboard Requirements>
<Next.js SSR vs CSR Docs>
<Frontend Architecture Review (Recording)>
Appendix: Other Options Discarded
Gatsby (Jamstack): Optimized for static sites, not suitable for logged-in, dynamic dashboards.
Electron App: Would add unnecessary complexity and platform overhead.
🔁 Why This Works
The goal of a TSD isn’t to be right—it’s to be rigorous.
It forces us to think through options clearly, avoid gut-driven decisions, and make context-aware trade-offs. It’s also incredibly valuable for onboarding new team members or revisiting decisions months down the line.
Most importantly, it keeps everyone aligned—not just developers, but designers, product managers, and stakeholders too.
So the next time you’re at a crossroads, before you default to the comfortable option, ask:
What are our real constraints?
What principles should guide this choice?
What are the trade-offs we’re willing to accept?
Then, write it down. Just a page or two.
You’ll be surprised how much clarity it brings.
Here is a ready to use template TSD_Template.
Let me know your thoughts on this strategy. In case you use some other techniques, please feel free to share in the comments.