Building for the Next Engineer: Code That Outlasts You

When I left Home Depot, not a single Slack message asked me "how does this work?" My systems kept running. My pipelines kept deploying. My dashboards kept updating.

That wasn't luck. It was the most intentional part of my engineering practice: building for the person who comes after me.

The Test

Before I consider any system "done," I ask: "Could a mid-level engineer, who has never seen this code, operate it without contacting me?"

If the answer is no, I'm not done. The code might work, but it's not complete.

What "Operability" Looks Like

1. README That Answers the First 5 Questions

Every new engineer asks the same 5 questions:

1. What does this do?
2. How do I run it locally?
3. How do I deploy it?
4. Where are the logs?
5. Who do I contact if it breaks?

```markdown

Quality Telemetry Dashboard

Fetches CI test metrics and displays build health across repos.

Run Locally

npm install && npm run dev

Open http://localhost:3040

Deploy

Push to main → Vercel auto-deploys

Logs

Vercel Dashboard → Functions → quality-api

On-Call

This system degrades gracefully. If GitHub API is down, it falls back to cached data. No pager required. ```

Twelve lines. Answers all five questions. The next engineer is productive in 5 minutes.

2. Runbooks, Not Tribal Knowledge

When something goes wrong, the fix shouldn't live in someone's head:

```markdown

Runbook: Dashboard Shows Stale Data

Symptom

Dashboard metrics haven't updated in >24 hours.

Diagnosis

1. Check GitHub Actions: is the daily cron job running? → github.com/JasonTeixeira/qa-portfolio/actions
2. If cron failed: check the error log for rate limiting
3. If cron succeeded: check if the artifact was uploaded → Look for qa-metrics artifact in latest run

Fix

• Rate limited: wait 1 hour, re-run manually
• Artifact missing: check test suite for failures
• API changed: check GitHub's changelog for breaking changes

Escalation

This is non-critical. Dashboard degrades to snapshot mode automatically. Fix during business hours. ```

I have runbooks for every failure mode in every system I build. They take 15 minutes to write and save hours of debugging for the next person.

3. Inline Comments That Explain WHY

```typescript // Bad: describes WHAT (I can read the code) // Increment retry count retryCount++;

// Good: describes WHY (I can't read your mind) // Retry up to 3 times because GitHub's artifact API // returns 404 for ~5 seconds after a workflow completes. // See: https://github.com/actions/upload-artifact/issues/270 retryCount++; ```

The best comments are links to issues, RFCs, or conversations that explain WHY a non-obvious decision was made.

4. Error Messages That Help

```typescript // Bad throw new Error('Invalid input');

// Good throw new Error( `Strategy timeframe "${timeframe}" is not supported. ` + `Valid options: 1m, 5m, 15m, 1h, 4h, 1d. ` + `See: docs/api/strategies.md` ); ```

The second error message tells the next engineer exactly what went wrong, what the valid options are, and where to learn more. They fix the issue in 30 seconds instead of 30 minutes.

The Career Impact

Building for operability isn't just good engineering — it's career insurance. When my systems run without me:

• My reputation persists. "Jason's system just works" is said long after I've left
• I leave on good terms. No hostage situation where I'm the only person who knows how it works
• References are stronger. "He built systems that survived his departure" is the highest compliment a manager can give

Build systems that outlast you. It's the most generous — and most strategic — thing you can do.