Skip to content
Shell
5.4 KB
Raw Blame

DECISIONS.md

Decision-Making Framework for Technical Choices

A Sr Dev's value isn't knowing the right answer - it's knowing the right questions.


The Core Questions

Before any significant decision, answer these:

1. What problem are we actually solving?

  • State it in one sentence
  • If you can't, the problem isn't clear yet
  • "Build X" is not a problem statement. "Users need Y" is.

2. What are the constraints?

  • Time: When does this need to ship?
  • Resources: Just Eddie? Team? Budget?
  • Technical: What must we integrate with? What's already built?
  • Knowledge: What do we know how to do vs. need to learn?

3. What are the options?

  • Always generate at least 2-3 options
  • Include "do nothing" or "defer" as a valid option
  • Include the "boring" option (proven tech, simple approach)

4. What are the tradeoffs?

For each option:

  • Pros: What does this give us?
  • Cons: What does this cost us?
  • Risks: What could go wrong?
  • Reversibility: Can we change our mind later?

5. What's the simplest thing that could work?

  • Start here. Add complexity only when forced.
  • "We might need X later" is not a reason to build X now.

6. What would make this the wrong choice?

  • Pre-mortem thinking
  • If we learn X, does this decision still hold?
  • What assumptions are we making?

Decision Types

Reversible vs. Irreversible

Reversible (move fast, course-correct):

  • Library/framework choices (usually)
  • UI patterns
  • Most feature implementations
  • File structure

Irreversible (slow down, think hard):

  • Database schema (core entities)
  • Authentication/authorization model
  • Public API contracts
  • Data architecture (what you store, how you access it)
  • Platform choice (iOS vs. Android vs. Web vs. all)

Now vs. Later

Decide Now:

  • Blocking current work
  • Affects other decisions downstream
  • Cost of delay > cost of being wrong

Decide Later:

  • More information coming
  • Not blocking anything
  • Reversible anyway

Platform Decision Framework

Specific to Eddie's common question: iOS/Android/Web

Questions to Ask

  1. Where are your users?

    • Consumer app → Mobile-first likely
    • Business tool → Web-first likely
    • Creative tool → Depends on workflow
  2. What native capabilities do you need?

    • Camera, GPS, sensors → Native or React Native
    • Files, offline → Native handles better
    • Just data display/input → Web/PWA fine
  3. What's your iteration speed need?

    • Web deploys instantly
    • Mobile has app store delays
    • If learning fast matters, web first
  4. What's your maintenance capacity?

    • Each platform = ongoing cost
    • Cross-platform reduces but doesn't eliminate

Common Patterns

Situation Recommendation
Validating idea fast Web (PWA if mobile feel needed)
Consumer app, broad reach React Native or Flutter
Performance-critical native features Native iOS + Native Android
Internal tool / small audience Web
Existing web app, adding mobile React Native (share logic)

Technology Selection Framework

The Boring Technology Principle

"Choose boring technology." - Dan McKinley

Every new technology has a learning curve, unknown failure modes, and integration cost. You have a limited "innovation budget."

Spend innovation tokens on:

  • Your core differentiator
  • Problems with no boring solution

Use boring tech for:

  • Everything else

Questions for Technology Choices

  1. Who else uses this in production?

    • Large-scale usage = battle-tested
    • "Hot new thing" = you're the beta tester
  2. What's the community/support like?

    • Stack Overflow answers?
    • Active maintenance?
    • Documentation quality?
  3. Does it fit the existing stack?

    • Consistency has value
    • Adding a new language/framework has cost
  4. What's the escape hatch?

    • If this doesn't work, how do we migrate?
    • Avoid lock-in on critical paths

Documentation Template

When making a significant decision, document it:

## Decision: [Title]
**Date**: YYYY-MM-DD
**Status**: Proposed / Accepted / Superseded
**Project**: [Project Name]

### Context
What situation are we in? What forced this decision?

### Options Considered
1. **Option A**: [Description]
   - Pros: ...
   - Cons: ...

2. **Option B**: [Description]
   - Pros: ...
   - Cons: ...

### Decision
We chose [Option X] because [reasoning].

### Consequences
- We will need to...
- This means we can't easily...
- We're accepting the tradeoff of...

### Review Trigger
Revisit this decision if: [conditions that would change the calculus]

Anti-Patterns in Decision Making

❌ Analysis Paralysis: Researching forever, never deciding → Set a timebox. Decide with 70% confidence.

❌ Hype-Driven Development: Choosing tech because it's trending → Ask: "Who's using this in production at scale?"

❌ Resume-Driven Development: Choosing tech to learn something cool → Ask: "Does this serve the project or just me?"

❌ Premature Optimization: Building for scale you don't have → Ask: "What's the actual load today? In 6 months?"

❌ Sunk Cost Commitment: Sticking with bad choice because you invested → Ask: "If starting fresh today, would I choose this?"


Remember

"The best decision is often the one that preserves optionality."

When uncertain:

  • Defer irreversible decisions
  • Make reversible bets
  • Build to learn, not to last
  • Ship and iterate