How to write a post that explains a technical decision

If you want to know how to write a post that explains a technical decision, start with the decision itself, then give the reasons in the order a reader needs them. Open with what you chose and why in two sentences. Then cover the problem, the constraints, the options you rejected, the trade-offs you accepted, and what would make you revisit the call. A reader who stops after the first paragraph should still know the answer.

Electrified gives you your own page at /@handle where articles like this live, each filed under topics you choose, with a feed people can follow.

Decisions often get made in chat threads, meetings and pull request comments, where the reasoning is easy to lose. A new person who finds the code may take it for an accident and propose the change you already ruled out.

A decision post fixes that. It records what you knew at the time, what you weighed and what you gave up. It also gives you something to link when the question comes up again, so you stop retelling the story.

Keep it to one decision per post. This follows the same rule as a concept note: one idea per article. If you made three choices, write three posts and link them to each other.

Start with the context and the problem

Open with the answer, then explain how you got there. Here is a worked example. Imagine a two-person team that needs background jobs: send emails, resize uploads, retry failures. The first paragraph could read:

We run background jobs from a table in our existing database instead of adding a message broker. It keeps our setup to one moving part, and it is enough for our current volume. We will revisit it if job volume or retry needs outgrow a table.

After that, describe the problem in plain terms. Say what was going wrong or what was missing, who felt it, and when it started to matter. Write "uploads are resized inside the web request, so slow images make pages time out" rather than "we needed asynchronous processing".

Name the date and the state of the system. A decision made when you had one server and two developers reads differently from one made with ten of each.

State the constraints and decision criteria

Constraints are facts you could not change. Criteria are the things you used to judge the options. Readers often disagree with a decision because they assume different ones, so write both down.

For the job queue example, the constraints might be:

• Two developers, and nobody on call for infrastructure.
• The app already runs on one database that is backed up and monitored.
• Jobs must not be lost if the server restarts.

The criteria might be, in order of weight: how few new things we have to run, how easy failures are to inspect, and how well it scales later. Put them in order. Ranking them is what lets a reader follow your choice even if they would have ranked them differently.

Lay out the options you considered

Give each realistic option a short section or a bullet with the same three parts: what it is, what it does well, and where it falls short against your criteria. Treat the options fairly. If you describe the rejected ones as obviously bad, readers will not trust the rest.

For the example, the options could be:

• A jobs table in the existing database. One less service to run, and failed jobs can be read with an ordinary query. Polling adds some load and delay.
• A dedicated message broker. Built for this, with good delivery handling. It is one more service to deploy, secure, monitor and restore.
• Keep doing the work in the request. No new parts, but it does not fix the timeouts, which is the problem we started with.

Include the "do nothing" option when it is real. It shows the problem was worth solving.

Explain the choice and the trade-offs you accepted

The diagram shows the order the sections follow, with the choice first and the costs last.

The order a decision post follows, from the choice to the costs.

This is the heart of the post. Say which option won and tie it back to the criteria you ranked. "The table wins on the first two criteria and is acceptable on the third" is a clear, checkable claim.

Then say what you gave up. Every decision costs something, and a post that names nothing you gave up is a sales pitch. In the example you might write: "We accept slightly delayed job pickup, and we accept that heavy volume would put load on the main database."

Also say who pays that cost. If the trade-off lands on the on-call person or on a future team, say so. That honesty is what makes a decision post useful later.

Show the evidence: benchmarks, tests, and examples

Claims about performance, reliability or effort need something behind them. Show what you ran, on what, and what you saw. Use your own measurements, not numbers borrowed from somewhere else.

• Say how you tested. Describe the machine, the data size and the steps so a reader could repeat it.
• Show a real example. A short snippet of the query you use to list failed jobs, written as inline code, does more than a paragraph of description.
• Report what surprised you. If a result went against your expectation, include it.
• Say what you did not test. A gap you name is better than one the reader finds.

If you have no measurements, say that the decision rests on reasoning and experience. That is a fair thing to write. Making up precision is not.

Say what would change your mind

Close the reasoning with explicit triggers. They turn a one-off opinion into a plan. For the example:

• If jobs per minute pass the level where polling slows normal queries, we move to a broker.
• If we need delivery guarantees across several services, we move to a broker.
• If a third developer joins and takes on infrastructure, we reconsider.

Write your own thresholds from your own measurements. A trigger like "when the jobs table starts showing up in our slow query review" is concrete enough to act on. When a trigger fires, write a follow-up post and link both ways, so the history stays readable.

A template for a post that explains a technical decision

On Electrified, choose Article in the editor. A note is limited to 500 characters and has no title, so it only suits a one-line decision. An article has a title of up to 140 characters and as many sections as it needs. Start each section with ## and a heading. Here is a skeleton to copy:

1. Title: the decision, stated as a fact. "We run background jobs from a database table".
2. Opening paragraph: the choice, the main reason, and when you will revisit it.
3. ## The problem: what was wrong, who felt it, the date and the state of the system.
4. ## Constraints and criteria: fixed facts, then your ranked criteria.
5. ## Options: each realistic option, with strengths and weaknesses against the criteria.
6. ## The decision and its costs: the choice, why it won, what you gave up.
7. ## Evidence: tests, examples, and what you did not test.
8. ## What would change this: the triggers for a second look.

The body box has Write and Preview tabs, and the preview looks like the published page, so check headings and lists there. The editor reads **bold**, *italic*, links, lists, quotes and numbered lists.

Add up to 5 topics, separated by commas. Each topic links to a page of every post about it, so people reading about one decision can find your others. You can see what exists on the topics page.

Press Save draft first. A draft is visible only to you, and no search engine sees it. Publish when the reasoning holds up on a second read. A published post keeps its address, so you can edit it with Save changes when a trigger fires or a number changes, and links to it keep working.

If you plan several decision posts, a single start-here post can point readers to them in order. When you want a quick reference for the options, a cheat sheet works well beside the full reasoning.

Frequently asked questions

How long should a technical decision post be?

Long enough to cover context, options, the choice, its costs and the triggers, and no longer. If a section does not change how a reader judges the decision, cut it.

Should I include the options I rejected?

Yes. The rejected options are what stop the same proposal coming back. Describe each one fairly and say which criterion it failed.

What if the decision turns out to be wrong?

Write a short follow-up that says what you learned and what you changed, and link it to the original. You can also edit the original and add a note at the top pointing to the new post.

Do I need benchmarks to justify a decision?

No. If you have measurements, show how you got them. If you do not, say the choice rests on reasoning and experience, and name what you would measure later.

Should this be a note or an article?

Use an article. A note is capped at 500 characters with no title, which only fits a one-line summary of a decision.

Get started

Pick one decision your team made recently and write down the answer in two sentences. Then fill in the template one section at a time, saving as a draft as you go. Publish when a colleague who was not in the room could follow it.

Make an account on Electrified: write about your product, topic or idea on your own page, one article at a time, and let readers follow along.