The principles
- What are you actually trying to do?
- Software SNR
- Separate the what from the how
- Requirements name the need, not the solution
- Start everyone from the same baseline
- Plan the build, and show something real
- Finish the handoff
- Build for the need in front of you
- The straight path is often the fastest
- Subtract a technology and look again
- How the principles work together
A short, shared vocabulary for the part of engineering that the tools never teach: how to keep a project honest. Each principle is something you can say in a review, hand to a newer engineer, or hold yourself to on a quiet afternoon. The goal is a team that spends its hours on the part that matters and leaves behind work the next person is glad to inherit.
These principles are domain-agnostic on purpose. They apply to a satellite ground station and to a weekend script in equal measure, because each one is about the relationship between the work and the need it serves. Read them in order the first time; after that, reach for whichever one fits the afternoon.
01 · The root question
What are you actually trying to do?
The most useful sentence in engineering is a question, and it is almost embarrassingly simple: what are you actually trying to do? Asked early and asked kindly, it gives everyone in the room the same target. A clear answer to that one question protects more schedule than any framework or tool ever has, because it heads off the most expensive outcome in all of engineering — building the wrong thing beautifully.
It works precisely because it is gentle. It assumes good faith, invites the asker to think out loud, and turns a vague request into something a team can aim at. When you offer that question to a teammate, you are handing over a clearer version of the goal than the one that walked in the door.
Build the thing that was asked for
Take the request at face value and start coding the literal ask. Quick off the line — and three weeks in, it turns out the ask was a guess at the real need.
Build the thing that is needed
Spend five minutes on “what are you actually trying to do?” first. The real need surfaces, and the build aims at it from the very first line.
02 · A ratio worth measuring
Software SNR.
Borrow a term from the radios. Signal is the code that accomplishes the actual need. Noise is everything else — code that serves a pattern for its own sake, formats data nobody asked to see, or exists to satisfy a convention rather than a customer. Software SNR is simply the share of a codebase that is signal, written as a percentage with all the code as the denominator. A healthy target is 90 to 95 percent.
The fastest way to feel it is to write the same need twice. The job, both times, is one sentence: is the recent average temperature over the limit?
Strong signal — nearly every line does the job
Read it once and you know what it does. The need, the inputs, the math, the answer. Nothing here exists to satisfy a pattern.
Weak signal — the same job, hunting for the one line that matters
Three lines do the job. The rest is a pattern wearing the costume of engineering. Both files ship the same answer; only one of them is kind to the next reader.
Same need, same answer. The difference is how much a reader has to wade through to find the three lines that matter. The number is a conversation starter, not a grade.
The real gift of the term is that it converts a matter of taste into a matter of measurement. Instead of “I would have written this differently,” a reviewer can ask, “what’s the SNR of this change?” Now the discussion is about counting, together — which signal is load-bearing and which lines are along for the ride. That is a conversation everyone at the table can win.
And it pays a dividend forward. When the signal is easy to find, the next engineer can read the code, trust it, and change it safely. High SNR is a quiet act of generosity toward whoever comes next.
03 · Two different muscles
Separate the what from the how.
The most valuable question in a design review costs nothing to ask: what is missing today, and what has to be true to bridge the gap? Generating that question is critical thinking, and it falls straight out of the willingness to look at the whole problem rather than the corner of it in front of you. A CPU and an FPGA on one board, a customer who wants runtime control — therefore something has to carry runtime commands from one to the other. Where is it? You can ask that without knowing the words for the answer.
Knowing how to bridge the gap — the register block, the protocol, the bring-up sequence — is where deep experience earns its keep. These are two distinct muscles, and the encouraging part is that the first one is free. Anyone willing to own the problem out to its real edge can generate the question today, on day one, with no breadth of prior solutions required.
Asking the question
Pure critical thinking. Reason from the need, look at the whole system, and notice what has to exist for it to work. Costs only the willingness to lift your eyes to the edge of the problem.
Answering it well
Where breadth shines. The named techniques, the heritage, the right interface. Experience makes the answer precise and turns a good question into a shipped bridge.
A word used a lot here: shape
Shape is the structure of a thing — its parts and how they relate — before any specific values are filled in. The shape of a problem is what kind of problem it is and what has to be true to solve it. The shape of a system is its pieces and the boundaries between them. Naming the shape is the breadth view: you can draw it on a whiteboard, and a room can agree on it, long before anyone picks a number, an address, or an algorithm. Most of this chapter is about getting the shape right first.
Here is what the breadth view looks like on paper. Picture a board with an operator console, a flight computer, and a sensor FPGA. Before anyone opens a datasheet, you can already name what has to cross each boundary and which way it flows. That is the what — the system seen whole.
Write that down as an Interface Design Description — an IDD — and at this altitude it stays deliberately about the what. A row says a message goes from A to B and why. It does not yet say at what address, in what byte order, or how fast. Keeping values out on purpose is the discipline: it lets the whole team agree on the shape of the system in an afternoon, long before anyone commits to the hard parts.
| ID | From | To | What it carries | Dir | When | |
|---|---|---|---|---|---|---|
| 1 | IF-01 | Operator console | Flight computer | Mode command (set sample rate, arm, safe) | → | On operator action |
| 2 | IF-02 | Flight computer | Sensor FPGA | Configuration block | → | At startup and on mode change |
| 3 | IF-03 | Sensor FPGA | Flight computer | Telemetry samples | → | Continuous while armed |
| 4 | IF-04 | Sensor FPGA | Flight computer | Health and status | → | Periodic heartbeat |
This is the expectation at the principal level and above: know how to ask. The separation is also a kindness to a newer engineer, because it means he or she does not have to have seen every solution to be useful. Reasoning from the need is available to everyone from the first day; the breadth to phrase the answer arrives with the years.
My part is the datapath
Draw the boundary at the edge of your own block. The math is proven, the box is closed, and the question of how the rest of the system talks to it never gets asked.
My part is the system edge
Lift your eyes to the whole board and ask what has to cross each boundary. The missing interface shows up early, while it is still cheap to add.
04 · Tell them apart
Requirements name the need, not the solution.
People often arrive with a solution wearing the clothes of a requirement. “We need Kubernetes” is a proposed answer; the need underneath is usually closer to “we want deployment and scaling to take care of themselves.” “We need a caching layer” often means “reads have to stay fast as traffic grows.” Translating the ask gently back to the need is one of the highest-leverage things an engineer can do, because the moment the real need is on the table, simpler paths to it tend to appear on their own.
When a very specific technical question shows up — “how do I read byte 47 of this packet?” — zoom out and ask what the goal is. Often the goal (“get the timestamp”) has a cleaner route than the route the asker had already committed to. Asking the wider question is a favor, not a correction.
Build the solution as stated
“We need Kubernetes” becomes the requirement, and the team builds Kubernetes. The need underneath is never examined, so a simpler path is never found.
Name the need behind it
Translate it to “deployment and scaling take care of themselves,” and the real options open up — often simpler than the one first named.
05 · One starting line
Start everyone from the same baseline.
A project moves fastest when everyone begins from the same picture. The artifact that creates that picture is the product requirements document — the PRD. Think of it as the baseline: a shared, written statement of what the team is building and why, parked somewhere the whole team and the customer can see it. It is principle 1 and principle 4 — what are you trying to do and name the need — written down once, for everyone at the same time.
- Goals
- What success looks like, in plain language a customer would recognize.
- Business objectives
- Why this is worth doing, and why now.
- Strategic fit
- How it serves the larger plan and the products around it.
- User stories
- Who needs what, and to what end — the work seen from the person using it.
- UX and interactions
- How a person meets the system: the touch points and the flow between them.
- Open questions
- What is still unknown, named honestly so it can be answered out loud.
- Scope
- What is in — and, just as usefully, what is out for now.
Here is the freeing part: a PRD is not a finished design, and it does not have to answer every question. Its job is smaller and far more powerful than that. It gets people thinking and communicating quickly, from a common starting point, and it turns a hallway full of quiet, differing assumptions into one page everyone has read. Open questions are a feature of a good baseline, not a flaw — they show the team exactly where to point its attention next.
Lead with a project summary.
Before any of that structure, the very first thing to write is the project summary — and it is the most useful page in the whole PRD. The project summary is short, a page or two, told in plain English through the eyes of the customer and the engineers who will live with the result. It does not specify; it describes. It answers the plain questions a customer actually has: what do I get for my money, how do I use it, how is it installed, and how do the results reach me — and it states, in one clear direction, how the team intends to build it. Then it asks the only question that matters this early: you good with it?
It is deliberately incomplete. It wanders into the physics where the physics matters, and into the internals when the customer cares about them or when a task smells hard enough to deserve a closer look. It carries a diagram or two — cheap ones, sketched, never the kind that costs a week of Ansys time on thermals and airflow. The one exception is worth stating plainly: if a gut feel says the project may push against a physical limit and you do not yet know how to handle it, that is exactly the moment to stop and resolve the fundamentals first — a quick pass through the power, mass, link, and timing budgets — before promising anything you cannot deliver.
Then it goes around the room. The summary is shared with the customer and the few engineers who need to know — usually the leads — and passed back and forth until everyone is happy. As the team grows, it is the document a new engineer reads first. Because it is plain and short and written from the reader’s point of view, it does something a spec never does: it surfaces requirements and easy-to-miss details on its own, and it cures the blank-page paralysis that stalls so many starts. It is one of the first things to write — and when an RFI lands on the desk, a little cleanup turns this same summary into the response.
Here is what one looks like, early and unpolished, for a device a customer wants built to catch illegal deforestation in time to do something about it.
Project summary: catching the cut in time
Draft v0.1 · customer + leadsWhat you get is early warning. When illegal logging starts inside the preserve, you learn about it within minutes — roughly where it is happening and how sure we are — while there is still time to send someone. The deliverable is two parts: a set of low-cost sensor nodes spread across the area, and a small base station at your post that turns what they hear into an alert you can act on. The value is not any single node; it is blanketing the area for less than the cost of an hour of helicopter patrol.
How you would use it
Day to day, you do nothing — the system watches. When a node is confident it is hearing a chainsaw or a logging truck, the alert reaches you the way you prefer: a text to the on-call phone, an email to the team, and a flag dropped on a simple map on the base-station computer showing which part of the preserve lit up. Nothing fancier than that is needed to act on it.
How it is deployed
Each node is a small, rugged unit fixed to a tree, switched on and logged at its location once. It runs for a season on a battery and is cheap enough to leave or collect at the end — no wiring, no tower of its own, no field maintenance. You scatter enough of them to cover the ways a crew would get in. Each node decides on its own whether a sound is real before it says anything, which is what keeps you from chasing phantom chainsaws; one node gives a rough area, and several hearing the same event narrow it to a spot worth driving to.
Getting the alert out of the forest
The harder question is how a node deep in the trees reaches your base station with no cell coverage. The obvious first answer is a single long-range radio from each node straight to the post, so I ran the link budget for it — and over these distances, under wet canopy, it does not quite close. It is close, though, and that points the way. The direction I would build to is a mesh: nodes pass the tiny alert from one to the next until it reaches a gateway placed high, on an existing tower or a clear ridge, and the gateway forwards it to your station. If a far corner stays out of reach, one repeater covers it. A lower radio band that punches through foliage better is the alternative I am holding in reserve — but mesh-to-a-high-gateway is the plan.
The part I will not promise yet
One thing is genuinely uncertain: whether a node can listen all season and keep enough power to relay, on a battery cheap enough to call disposable. That is a real energy question, and right now I do not know the answer — the honest thing is to say so. Rather than quote a date I would have to walk back, I would propose a three-month, cost-plus research phase: build a handful of real nodes, measure power draw and canopy range in the field, and try the levers — how often we listen, that lower band, a small solar top-up. At the end you get a clear yes-or-no and a firm direction, having spent research money instead of a full build on a guess. This is a hard problem; that is why it landed on your desk, and then on mine. If it were easy, it would not need engineering.
Here’s the direction. You good with it? The questions it raises — how far the radio reaches under canopy, how long a node lasts against how often it listens, how tightly we can place an event, how low we can drive false alarms — are not gaps in the plan. They are the first requirements, already found, before a dollar goes toward building the wrong thing.
We all basically know the plan
Skip the written baseline and start building. Each person carries a slightly different private picture, and the differences only surface once the pieces collide.
We all read the same page
Write the one-page baseline first. The picture is shared, the open questions are visible, and the collisions happen on paper, where they cost nothing.
06 · A visible slice beats a promise
Plan the build, and show something real.
With the baseline set, there is a natural pull to build the whole thing before showing anyone. The stronger move is to lay the work out as a plan you can point to, and then deliver it in slices. The feature matrix is that plan on one page: each feature, how much it matters, which release it belongs to, and the need it traces back to. It keeps the build honest against the PRD, the customer’s expectations, and the game plan all at once.
| Feature | Priority | Release | Traces to | Status |
|---|---|---|---|---|
| Live telemetry view | Must | v0 | Goal: operator sees the system is alive | Done |
| Set sample rate | Must | v0 | User story: tune the capture | In progress |
| Arm / safe control | Must | v1 | Safety requirement | Planned |
| Health heartbeat | Should | v1 | Reliability objective | Planned |
| Recorded export | Could | v2 | Stretch goal | Planned |
Then sequence it. Pick a first slice that puts something a person can see and touch in front of the customer, even while most of the matrix is still ahead of you. A working sliver lights a customer up in a way no status report can match — a demo is more than a promise of a demo. Seeing beats hearing.
v0 · first thing the customer sees
Watch it live
Telemetry on the screen, sample rate adjustable. Rough edges everywhere — and the customer is already leaning in.
v1 · operate it
Drive it safely
Arm and safe controls, a health heartbeat. Now it is a system someone can run with confidence.
v2 · live with it
Keep the record
Recorded sessions, longer runs, the stretch goals. The parts that matter once the core is trusted.
Showing something early is generous, and it quietly de-risks the whole program. It surfaces a misunderstanding while it is still cheap to fix, and it builds a kind of trust that compounds with every slice. The customer stops buying a promise and starts watching progress.
Get a prototype into their hands.
That first slice has a name worth using carefully: the prototype. A prototype is the build that meets the functional requirements and little else — it may run on an evaluation board instead of the real hardware, the enclosure may be cardboard, the screen may be ugly — but it does the thing well enough for the customer to see it work and react to it. The goal is to get one into the customer’s hands fast: somewhere between the first week and the first month, depending on how hard the project is. A prototype someone can poke at in week three beats a flawless plan they read in month three.
It is worth keeping the prototype distinct from the MVP. The minimum viable product is the smallest version that delivers real value to a real user in the field. The prototype comes earlier and aims lower: it only has to prove the function and earn the conversation. One is for learning whether the idea works at all; the other is for shipping the first genuinely useful version. Build the prototype to learn fast, then grow it toward the MVP once the shape is confirmed.
Reappear when it is done
Go quiet for three months and return with a finished build. The customer’s first look is also the first chance to learn it is slightly wrong.
Show a slice early
Put a rough, working v0 in front of the customer fast. Course corrections arrive while they are still small, and trust grows with every slice.
07 · Making it is half the job
Finish the handoff.
Now return to that interface from principle 3. Building the FPGA logic is one half of the work. Telling the next engineer how to work with it is the other half, and it carries equal weight. The software on the CPU has to know the registers, the power-on sequence, and the timing — or the bridge that looked finished is only half built. This is where the IDD grows up: the what from principle 3 gains its how.
| Offset | Register | Access | Reset | Purpose |
|---|---|---|---|---|
| 0x00 | CTRL | R/W | 0x00 | enable, reset, mode select |
| 0x04 | STATUS | R | 0x01 | ready, armed, error flags |
| 0x08 | SAMPLE_RATE | R/W | 0x0A | samples per second |
| 0x0C | DATA | R | 0x00 | latest telemetry sample |
| 0x10 | HEALTH | R | 0x00 | heartbeat counter, fault code |
And the part a register map alone never tells you: the order to do things in. A power-on sequence turns a table of addresses into a part that actually comes up.
- Apply power and wait for
STATUS.readyto read 1. - Write
SAMPLE_RATEwith the configured value. - Set
CTRL.enableto begin sampling. - Read
DATAon each new sample, by polling or by interrupt. - Read
HEALTHon the heartbeat interval and act on any fault code.
None of this is busywork, because every line of it traces back to something a person asked for. That tracing is what keeps depth honest: the how stays tethered to the what, the UX, and the requirements.
Then prove the boundary holds, on its own, before another team builds on top of it. Test it two ways:
Does it behave per the contract?
Each register reads and writes as the IDD says. The power-on sequence brings the part up every time. Tested at the boundary, against the written interface, in isolation.
Does it hold up under real conditions?
Timing and throughput meet the need. A bad write is rejected gracefully; a dropped sample is handled. The boundary stays trustworthy when the day gets messy.
A tested, documented interface is a gift to the team. It lets whoever integrates next move fast and trust the boundary completely. The alternative is quieter and costlier: an untested, undocumented interface hands your unfinished work to the next engineer as an unspoken transfer of ownership — he or she inherits the parts you left undone without ever agreeing to. Finishing the handoff keeps ownership where it belongs and lets the whole system move together.
It works on my bench
Hand over the logic and let the registers speak for themselves. The next team inherits an undocumented, untested boundary as an unspoken transfer of ownership.
Hand over a boundary others can trust
Ship the register map, the power-on sequence, and the isolation tests alongside it. The integrating team moves fast, and ownership stays where it belongs.
08 · Right-size the ambition
Build for the need in front of you.
“At scale” is usually a phantom — a future that may arrive on a schedule nobody can name, quietly spending today’s budget on a load that has yet to show up. The grounded move is to build well for the real, present need, and to add flexibility the moment it is genuinely wanted. That timing keeps the SNR high and the design honest, and it leaves room to grow in the direction the work actually grows.
Extensibility is a fine thing — a wonderful thing — to add when someone truly asks for it. Adding it on spec, before the need is real, is how a clean idea picks up the weight it was supposed to avoid. Trust that the need, when it arrives, will tell you its shape more clearly than a guess ever could.
Build it for “at scale”
Engineer for a future load nobody has named yet. The generality nobody asked for arrives right on schedule; the signal it was meant to serve does not.
Build it for the real need
Solve the present need cleanly, and add flexibility the moment it is genuinely wanted. The design stays honest and ready to grow where the work actually grows.
09 · Speed comes from focus
The straight path is often the fastest.
A surprising amount of engineering speed comes from removing the coordination tax rather than adding people to the problem. A focused engineer who owns a piece end to end can often write the right thing from scratch faster than a group can extend something that merely almost fits. The honest measure is days-to-weeks of clear, owned work against months of negotiation around a near-match.
Reuse is genuinely excellent when the fit is real — lean on it hard in that case. The judgment call is the near-fit: when a library covers eighty percent and fights you on the rest, the straight line is frequently to build the small, exact thing. Look for the straight line, and take it when you can see it clearly.
Bend the project to the near-fit
Adopt the library that covers eighty percent, then spend months wrapping, patching, and negotiating the stubborn other twenty.
Take the straight line
When a thing only nearly fits, write the small exact piece in days — and lean hard on reuse wherever the fit is genuinely real.
10 · Take away your favorite tool
Subtract a technology and look again.
Here is a question that reliably shakes a simpler design loose: what if I did not have X — could I still build this another way? Pick the part you reach for by reflex and take it away, on paper. The classic one to remove is the FPGA. Ask what the design becomes with no FPGA at all, and a surprising number of times a cleaner path appears — often something a little old-school with a modern twist: a small microcontroller and clever timing, a purpose-built analog front end, a cheaper part doing one job well. Fewer moving pieces, lower cost, less to carry.
It does not always win, and that is the honest part. Sometimes the FPGA really is the right answer — the throughput, the parallelism, the hard determinism genuinely need it — and now you know exactly why, which is its own kind of win. The point of the question is not to ban a technology; it is to make sure the default earned its place instead of just showing up out of habit. Run it against whatever your favorite tool happens to be, and keep whichever design is simpler for the same result.
Reach for the usual stack
Start from the tools you always use; the FPGA goes in because the FPGA always goes in. The design quietly inherits cost and complexity no one questioned.
Remove it and look again
Ask what the design becomes with the part gone. Often a simpler, cheaper path appears; and when the part truly earns its place, you can finally say exactly why.
How the principles work together.
They share one spine. Start from the need. Keep the signal high. Ask the free question and own the problem out to its real edge. Tell a need apart from a solution. Get everyone onto the same baseline with a plain-English project summary, plan the build and get a real prototype into the customer’s hands early, and finish the handoff so the boundaries others lean on can be trusted. Build for what is actually in front of you, take a favorite tool away to find the simpler design, and let the straightest honest path win. Each principle reinforces the next: a clear need makes the signal obvious, a shared baseline makes the feature matrix honest, a visible prototype surfaces the real questions, and a finished handoff keeps the whole system moving.
It is about spending every hour on the part that matters — so the work ships, the customer receives exactly what was asked for, and the next engineer inherits something clear enough to build on. That is the whole game, and it is a game everyone at the table can win together.
Carry these into the rest of the guide. Requirements is principle four made rigorous. Design and trade studies is where the what-from-how split does its best work. Integration and Verification are where finishing the handoff gets tested in earnest. Lifecycle is where the baseline and incremental delivery keep a program honest from concept to retirement. And Leading the work turns the lens on the people and the clock — how a lead grows a team, sets direction, and estimates honestly. The chapters are the craft; these are the compass.