Side Project to Interview Gold: Document Your Decisions

You’ve just crushed the coding challenge. Your solution works, it’s clean, and you even threw in some tests. Now the interviewer asks, "Walk me through your thought process. Why did you choose React over Vue for this side project? Why did you use DynamoDB instead of Postgres?" Most candidates mumble something about "familiarity" or "it just felt right." That’s where you lose them. Your side project, if you treat it right, isn't just a portfolio piece; it's interview gold, a treasure trove of decision-making insights.

The real differentiator in a senior engineering interview isn't just knowing how to build something. It's knowing why you built it that way, and being able to articulate the trade-offs you considered. This isn't about memorizing design patterns; it's about demonstrating judgment, foresight, and the ability to think critically under constraints. The best way to show this? Document your decisions as you build.

The Secret Weapon: A Decision Log

Think of a decision log as your personal engineering journal for a project. It's not a commit message, it’s not a README (though it can inform one), and it’s definitely not a post-mortem. This is a living document you update as you make significant choices throughout your project’s lifecycle. It forces you to pause, reflect, and explicitly state your reasoning.

For example, I was building a small internal tool at my last job, a Slack bot that integrated with our CI/CD pipeline. Early on, I considered using AWS Lambda for serverless functions versus a small Node.js service running on an EC2 instance. I opened a markdown file called DECISIONS.md in my project root and jotted down:

• Decision: Use AWS Lambda with API Gateway for the Slack bot's backend.
• Date: 2023-10-26
• Context: The bot needs to respond to Slack events (HTTP POST requests) and occasionally trigger CI/CD jobs. Expected traffic is low, maybe a few hundred requests a day at peak. We have existing AWS infrastructure.
• Options Considered:
  1. AWS Lambda + API Gateway: Fully serverless, scales to zero. Low operational overhead. Cost-effective for low traffic.
  2. Node.js service on EC2: More control over the environment. Potentially lower latency for very high, sustained traffic if provisioned correctly. Higher operational overhead (OS patching, monitoring EC2 instance).
• Reasoning for Choice:
  • Cost: Lambda's pay-per-execution model is significantly cheaper for sporadic, low-volume requests. An EC2 instance, even a t3.nano, incurs constant cost.
  • Maintenance: Lambda functions require less maintenance. No OS updates, no server provisioning. We don't have a dedicated ops team for internal tools.
  • Scalability: While current traffic is low, Lambda handles unpredictable spikes effortlessly without me needing to configure auto-scaling groups.
  • Existing Infrastructure: Our team already uses AWS, so deploying Lambda functions is a familiar pattern.
• Trade-offs Accepted:
  • Cold Starts: Lambda functions can experience cold starts, adding a few hundred milliseconds of latency. For a Slack bot, this delay is acceptable. A user won't notice an extra half-second.
  • Vendor Lock-in: Tying heavily into AWS Lambda.
  • Debugging Complexity: Debugging distributed serverless functions can be more complex than a monolithic service on one machine. We have good CloudWatch integration, which helps.
• Alternative/Future Considerations: If the bot grew to handle millions of requests monthly or required complex, long-running background tasks, an EC2 instance or ECS might become more appropriate.

See that? It’s not just "I used Lambda." It's a mini-case study. This kind of entry takes 10-15 minutes to write, maybe 20 for a really big decision. But it pays dividends.

What to Document: Not Every Tiny Choice

Don't log every npm install or minor CSS tweak. Focus on decisions that have significant architectural, performance, security, or maintainability implications.

Here are some categories of decisions worth documenting:

• Technology Stack Choices: Why React vs. Svelte? MongoDB vs. PostgreSQL? Flask vs. FastAPI? GraphQL vs. REST? gRPC vs. HTTP/1.1? These are prime examples. Consider the project's scale, your team's expertise (even if that "team" is just you), and future growth.
• Architectural Patterns: Why a microservice over a monolith? Why event-driven instead of request-response? Why hexagonal architecture?
• Data Storage & Modeling: Choosing a specific database, deciding on a schema design, denormalization strategies. "I chose a document database because the data structure is highly fluid and schema changes are frequent, unlike a rigid relational model which would require migrations."
• Deployment Strategy: Serverless, containerized, PaaS, IaaS. Why did you pick one over the others? Cost, operational complexity, scalability needs.
• Key Dependencies/Libraries: Why did you pick axios over the built-in fetch API? Why redux-saga over redux-thunk? Often, it's about feature set, community support, or alignment with project patterns.
• Security Considerations: How did you handle authentication? Why OAuth2 vs. API keys? Data encryption at rest or in transit.
• Performance Optimizations: When you implemented caching, what did you cache and why? How did you identify the bottleneck?

The crucial part is not just stating the choice, but laying out the alternatives and the trade-offs. Every decision has trade-offs. If you can't articulate them, you didn't truly understand the decision.

Interview Scenarios: Turning Logs into Leverage

Imagine this: you're in a system design interview. The interviewer presents a problem. You immediately start thinking about solutions. But instead of just jumping to the "optimal" one, you mentally (or explicitly) run through the options, just like you did when writing your decision log.

"For this component, I'd initially consider a serverless function because of its low operational overhead for unpredictable traffic patterns. However, if latency becomes critical and cold starts are unacceptable, we'd look at a containerized service on ECS. That choice comes with increased management burden but offers more consistent performance. My experience building a Slack bot, where cold starts were tolerable, led me to prioritize cost and maintenance."

See how you just pulled from your documented experience? You're not just answering the question; you're demonstrating practical wisdom.

Another common scenario: the behavioral interview. "Tell me about a time you had to make a difficult technical decision." If you've been logging, you don't need to scramble through fragmented memories. You open your DECISIONS.md file, pick a relevant entry, and recount the situation with precision and depth. You'll sound articulate, thoughtful, and prepared. This isn't about memorizing a script; it's about having a detailed reference.

I once interviewed for a staff-level role where the interviewer asked about my experience with "database migrations for high-traffic services." I immediately thought of an older side project, a content aggregator, where I switched from MySQL to Postgres. My decision log entry detailed:

• Context: MySQL was getting hammered with complex join queries for user feeds. Performance was degrading.
• Options:
  1. Optimize existing MySQL queries, add more indexes. (Short-term fix, wouldn't scale.)
  2. Migrate to Postgres. (Better JSONB support for nested data, more robust analytical functions, better performance for complex queries.)
  3. Introduce a NoSQL layer for specific data. (Increased complexity, data consistency challenges.)
• Decision: Migrate to Postgres.
• Trade-offs: Downtime during migration window, learning curve for new features, need to rewrite ORM queries.
• Mitigation: Planned an overnight migration, used a dual-write strategy for a week to ensure data consistency, wrote extensive integration tests.

I walked them through the technical steps, sure, but the real impact came from explaining why Postgres, what alternatives I tossed aside, and what risks I accepted. That's the stuff that makes interviewers lean forward.

When Not to Document (and Other Caveats)

This isn't a silver bullet.

First, don't overdo it. If you're building a simple "to-do list" app with a standard MERN stack, you probably don't need a 20-entry decision log. The value comes from the complexity of the choices. If you're using a framework's default settings, you don't need to justify it unless you explicitly considered alternatives and rejected them.

Second, this takes discipline. It’s easy to get caught up in the flow of coding and forget to pause and document. Set a reminder, make it part of your "definition of done" for major features. A quick markdown file in your IDE is less friction than pulling up a Confluence page.

Third, your audience matters. While a decision log is for you, the skill it hones is for others. In a real team setting, these decisions would be discussed in design docs, RFCs, or team meetings. For a side project, you're simulating that process for yourself.

Finally, it depends on your career stage. If you're a junior engineer, explaining how you built something and showing working code is paramount. For a senior engineer, the why becomes equally, if not more, important. Interviewers expect you to have a broader perspective, to anticipate problems, and to make sound technical judgments under pressure. Documenting decisions helps you articulate this higher-level thinking.

Beyond the Interview: Better Engineer, Better Decisions

The benefits don't stop at landing a job. This practice makes you a better engineer, period.

• Improved Critical Thinking: You're forced to consciously weigh pros and cons. This strengthens your analytical muscles.
• Enhanced Communication: Articulating complex technical choices clearly is a fundamental skill. It helps you onboard new team members, justify proposals, and resolve disagreements.
• Historical Context: Months down the line, when you or a future maintainer needs to understand why a particular system looks the way it does, this log is invaluable. No more "who built this and why?" moments.
• Learning & Reflection: Reviewing past decisions helps you identify patterns in your own thinking, highlight areas for improvement, and avoid repeating mistakes. Maybe you consistently underestimate the operational overhead of self-hosting. Your log will show you that.

I've seen too many brilliant engineers struggle in interviews because they can't translate their hands-on experience into articulate explanations of their thought processes. They know what they did, but they can't explain why they didn't choose option B, or what trade-offs they accepted.

Start small. Pick one significant decision on your current side project. Write it down. See how it feels. You'll quickly realize how much depth you can add to your technical storytelling. Your projects will become more than just code; they'll become narratives of thoughtful engineering.

Ready to Ace Your Next Interview?

Practice with AI-powered mock interviews tailored to your target role and company. Start Practicing for Free | Explore Interview Prep