Documenting Trade-offs

In senior engineering roles, you aren't just paid to write code; you are paid to make decisions. And in software, there are no solutions-only trade-offs. If you choose a NoSQL database, you gain scalability but lose ACID compliance. If you choose a microservices architecture, you gain team independence but lose operational simplicity.

This lesson teaches you how to document these choices so your team (and your future self) understands the "Why."

The "Options Considered" Section

Every RFC or design doc should have an "Options Considered" section. This prevents the "Why didn't you just use X?" question during reviews.

For each option, list:

1. Description: What is it?
2. Pros: Why is this good? (Speed, cost, familiarity)
3. Cons: What are the downsides? (Complexity, technical debt, latency)
4. Risks: What could go wrong?

The Comparison Table

When choosing between two or three major paths, a table is the clearest way to communicate.

| Criteria | Option A (Serverless) | Option B (K8s) | | ------------------------ | --------------------- | -------------- | | Speed to Market | High | Medium | | Operational Overhead | Low | High | | Cost at Scale | High | Low | | Flexibility | Limited | High |

Communicating Technical Debt

Sometimes the best trade-off is the "quick and dirty" one to meet a deadline. This is fine, as long as it is documented as Technical Debt.

"We are choosing Option A (Hardcoded config) to meet the Alpha deadline. Trade-off: This will require 2 days of refactoring in Sprint 5 to support multi-tenancy. We accept this risk to unblock the sales team."

Key Phrases for Trade-offs

• "While Option A offers [Pro], it introduces [Con]."
• "We decided to prioritize [Metric A] over [Metric B] because..."
• "The primary constraint driving this decision was..."
• "We considered [Alternative], but rejected it due to [Reason]."

By documenting trade-offs, you move from being a "coder" to being an "architect." You show that you understand the business constraints and the long-term implications of your technical choices.

Glossed terms

When you must use a technical term, gloss it inline:

• We use a cache (a fast temporary store) to speed up repeat requests.

The parenthetical gloss lets the non-technical reader follow without stopping to look it up. After the gloss, you may use the term freely.

Avoid jargon piles

Jargon piles exclude non-technical readers:

• We implemented a RESTful microservices architecture with asynchronous event-driven communication over a Kafka message broker.

For a mixed audience, break this up:

• We split our system into smaller services that talk to each other. They communicate by sending messages, which makes the system faster and more reliable. (We use a tool called Kafka for the messaging.)

The second version keeps the meaning clear while preserving the technical accuracy.

Common mistakes

1. Jargon-first. Non-technical readers stop at the first acronym.
2. No analogies. Abstraction without a concrete image is hard to grasp.
3. No layering. One flat technical document loses the executive audience.

Practice

Explain a technical concept from your work to a non-technical reader:

1. Business meaning (one sentence): _
2. Analogy: _
3. Technical detail (for engineers, below): _

Example: Meaning: We made the app load faster. Analogy: It's like moving your most-used tools from a distant shed to a drawer on your desk. Detail: We added a Redis cache layer that serves repeated queries in under 5ms.

In the final lesson, you will learn technical writing etiquette: documentation, comments, and changelogs.