Technical Communication

Technical communication is the ability to explain complex technical concepts clearly. This guide covers how to explain code, architecture, and technical decisions to different audiences.

Explaining Code

When You Need to Explain Code

• Code reviews
• Onboarding new team members
• Technical discussions
• Interview walkthroughs
• Documentation

The Code Explanation Framework

Step 1: High-Level Purpose (10 seconds) “This function/module/service does [what] to solve [problem].”

Step 2: Inputs and Outputs (15 seconds) “It takes [inputs] and produces [outputs].”

Step 3: Key Logic (30-60 seconds) “The core logic works by [explain the algorithm/approach]. The important part is [key insight].”

Step 4: Edge Cases and Decisions (15-30 seconds) “One thing to note is [edge case/design decision]. We handle this by [approach].”

Example — Explaining a Function

Code:

def find_anagrams(word, word_list):
    sorted_word = sorted(word.lower())
    return [w for w in word_list if sorted(w.lower()) == sorted_word and w.lower() != word.lower()]

Explanation:

“This function finds all anagrams of a given word from a list of candidate words.

It takes two inputs: the target word and a list of words to search through. It returns a list of anagrams.

The core insight is that two words are anagrams if they have the same letters in the same quantities — which means they have the same sorted representation. So we sort the letters of the target word and compare it to the sorted letters of each candidate.

One thing to note: we exclude the word itself (the w.lower() != word.lower() check) because a word isn’t an anagram of itself. We also normalize to lowercase to handle case-insensitive comparison.“

Common Mistakes When Explaining Code

1. Starting at the line level — “First it creates a variable called sorted_word…” (too granular)
2. Reading the code aloud — Don’t narrate every line
3. Using jargon without context — “It uses a hash map” (explain why)
4. Skipping the why — Explain the purpose, not just the mechanics
5. Going too deep — Match detail level to your audience

Explaining Architecture

The Architecture Explanation Framework

Level 1: System Context (30 seconds) “This system serves [users/clients] by providing [core functionality]. It interacts with [external systems].”

Level 2: Major Components (60 seconds) “The architecture has [N] main components: [Component A] handles [responsibility], [Component B] handles [responsibility], etc.”

Level 3: Data Flow (30 seconds) “When a [request/event] comes in, it flows through [path]. The data is stored in [storage].”

Level 4: Key Decisions (30 seconds) “The key architectural decisions are [decisions]. We chose this approach because [reasoning].”

Example — Explaining a Web Application Architecture

Level 1: “This is an e-commerce platform that serves 100K daily users. It connects to payment processors (Stripe), shipping providers (FedEx, UPS), and email services (SendGrid).”

Level 2: “There are four main components:

• The frontend is a React SPA that handles the user interface
• The API gateway routes requests and handles authentication
• The order service manages the order lifecycle
• The inventory service tracks stock levels“

Level 3: “When a user places an order, the request hits the API gateway, which validates the JWT token and routes to the order service. The order service checks inventory, creates the order, and triggers a payment event. The payment processor calls back with the result, and we update the order status and send a confirmation email.”

Level 4: “We chose microservices over a monolith because the order and inventory services have different scaling needs — orders spike on Black Friday while inventory queries are steady. We use event-driven communication between services to handle this gracefully.”

Diagram Communication

When drawing architecture diagrams:

1. Start with the big picture — External users/systems first
2. Add components left-to-right or top-to-bottom — Follow the data flow
3. Label arrows — What data/request flows in each direction
4. Use consistent notation — Boxes for services, cylinders for databases, arrows for communication
5. Highlight key decisions — Call out why you chose specific technologies

Common Diagram Elements

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend   │────▶│  API Gateway │────▶│  Order Svc  │
│   (React)    │     │  (Kong)      │     │  (Node.js)  │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
                    ┌─────────────┐     ┌─────────────┐
                    │  Inventory   │◀────│   Database   │
                    │   Service    │     │ (PostgreSQL) │
                    └─────────────┘     └─────────────┘

Whiteboard Communication

During Interviews

Whiteboard (or virtual whiteboard) communication is a critical interview skill.

Before Drawing:

1. Clarify the problem — Ask questions
2. State your approach — “I’ll start by identifying the components, then draw the data flow”
3. Get buy-in — “Does this approach make sense?”

While Drawing:

1. Think out loud — Narrate as you draw
2. Draw boxes first — Major components
3. Add arrows — Data flow and communication
4. Label everything — Components, protocols, data formats
5. Pause for questions — Check understanding periodically

After Drawing:

1. Walk through a scenario — “Let’s trace a request through the system”
2. Highlight tradeoffs — “We chose X over Y because…”
3. Discuss scaling — “This works for 1K users, but for 1M we’d need to…”
4. Address bottlenecks — “The potential bottleneck here is…”

Whiteboard System Design Template

1. REQUIREMENTS (top left)
   - Functional: What does it do?
   - Non-functional: Scale, latency, availability

2. ESTIMATION (top right)
   - Users, requests/sec, storage, bandwidth

3. HIGH-LEVEL DESIGN (center)
   - Major components
   - Data flow arrows

4. DETAILED DESIGN (bottom left)
   - Database schema
   - API design
   - Algorithm details

5. TRADEOFFS (bottom right)
   - What we chose and why
   - What we gave up
   - How to scale

Thinking Out Loud

Why It Matters

In interviews, thinking out loud shows:

• Your reasoning process
• How you approach problems
• That you’re not stuck (even if you’re thinking)
• Your communication skills

How to Think Out Loud

Instead of: silence while thinking

Say:

• “Let me think about this…”
• “I’m considering two approaches here…”
• “The tradeoff between X and Y is…”
• “I need to clarify something…”
• “Let me break this down…”

Thinking Out Loud Patterns

For coding problems:

• “I’m going to start by understanding the input and output…”
• “My first instinct is to use a hash map because…”
• “The brute force approach would be O(n²), let me see if I can do better…”
• “I think a two-pointer approach might work here because…”

For system design:

• “Let me estimate the scale first…”
• “The key components I’m thinking about are…”
• “For the database, I’m considering SQL vs NoSQL…”
• “The bottleneck might be here, so I’d add a cache…”

For debugging:

• “Let me trace through the code with this input…”
• “The issue might be in this function because…”
• “I’d add a log here to see what’s happening…”
• “Let me check if this assumption is correct…”

Balancing Thinking and Talking

• Don’t narrate every thought — Share the relevant reasoning
• Pause when needed — “Let me think for a moment” is fine
• Resume with a summary — “Okay, I’ve thought about it and…”
• Be genuine — Don’t perform; communicate

Explaining Technical Decisions

The Decision Framework

When explaining a technical decision:

1. Context: What was the problem/requirement?
2. Options: What approaches did you consider?
3. Criteria: What factors mattered most?
4. Decision: What did you choose?
5. Reasoning: Why did you choose it?
6. Tradeoffs: What did you give up?

Example

“Why did you choose PostgreSQL over MongoDB?”

Context: “We were designing the backend for a financial application that needed to handle complex queries and maintain data integrity.”

Options: “We considered PostgreSQL, MongoDB, and DynamoDB.”

Criteria: “Our key requirements were: ACID transactions for financial data, complex query support for reporting, and strong consistency guarantees.”

Decision: “We chose PostgreSQL.”

Reasoning: “PostgreSQL gives us ACID transactions out of the box, supports complex joins and aggregations for reporting, and has strong consistency. Our team also had deep PostgreSQL experience.”

Tradeoffs: “The tradeoff is that we don’t get the horizontal scaling flexibility of MongoDB or DynamoDB. But for our scale (10K transactions/day), vertical scaling is sufficient, and we can add read replicas if needed.”

Adapting to Your Audience

For Engineers

• Use technical terms freely
• Focus on implementation details
• Discuss tradeoffs and alternatives
• Reference specific technologies and patterns

For Product Managers

• Focus on user impact and business value
• Explain technical constraints in terms of user experience
• Use timelines and milestones
• Avoid deep implementation details

For Executives

• Lead with business impact
• Use analogies for complex concepts
• Focus on risks, timelines, and resources
• Keep it high-level — they trust your technical judgment

For Non-Technical Stakeholders

• Use everyday analogies
• Avoid jargon entirely
• Focus on what it means for them
• Use visual aids when possible

Analogy Examples

Database indexing: “It’s like the index at the back of a textbook — instead of reading every page to find a topic, you look it up in the index and go directly to the right page.”

Caching: “It’s like keeping frequently used items on your desk instead of in a filing cabinet across the room. You sacrifice some space for much faster access.”

Load balancing: “Imagine a restaurant with multiple cashiers. A load balouncer is like the person at the door who directs you to the shortest line, so no single cashier gets overwhelmed.”

API: “An API is like a restaurant menu — it tells you what’s available and how to order it, without needing to know how the kitchen works.”

Practice Exercises

1. Explain your latest project to a friend who isn’t in tech. Can they understand the basics?

2. Walk through your code as if explaining to a new team member. Are you clear and structured?

3. Draw your project architecture on a whiteboard. Can you explain it in 3 minutes?

4. Practice analogies for 5 technical concepts. Can you explain them without jargon?

5. Record yourself explaining a technical concept. Listen back — is it clear? Concise? Well-structured?