Writing in Public Made Me a Better Engineer

I delayed publishing technical writing for a long time because I thought every article needed to teach something new.

That standard made writing feel like a performance. I would open a draft, imagine everything an expert might criticize, and close it before the first paragraph felt finished.

What changed was a smaller goal: document one decision clearly enough that I could understand it six months later.

That turned writing from a marketing task into part of my engineering process.

Writing exposes vague thinking

A solution can feel obvious while it exists only in code and memory. The gaps appear when I try to explain why it works.

Why did I choose a background queue instead of processing the request directly? What happens when the operation runs twice? Which data is trusted? What would cause the approach to fail at ten times the current load?

If I cannot answer those questions in plain language, the design probably needs more work.

Writing does not automatically make a technical decision correct. It makes the assumptions visible enough to challenge.

Start with a decision log

I no longer begin most notes with an introduction. I begin with a small decision log while the work is active.

The structure is simple:

Context: What problem am I solving?
Constraints: What limits the available choices?
Decision: What approach did I choose?
Tradeoffs: What gets better and what gets worse?
Evidence: What did I test or measure?

This takes a few minutes and captures the details that disappear after shipping. It also prevents a common problem in technical articles, where the final solution is presented as if it appeared fully formed.

Real engineering includes false starts and constraints. Those details are often the most useful part.

Separate notes from tutorials

Not every piece of writing needs to be a complete tutorial.

A tutorial promises a reproducible path for the reader. That means checking versions, listing prerequisites, testing each command, and maintaining the article as tools change.

A note can be narrower. It can explain an architecture choice, a debugging path, or one lesson from a project. It still needs accuracy, but it does not need to pretend to be universal.

This distinction helped me publish more consistently. I can write about what I know without stretching a project story into a definitive guide.

Prefer evidence over confidence

Technical writing becomes more credible when claims are connected to evidence.

Instead of saying a page became "much faster," I can describe what changed in the bundle, the measured load time, and the test environment. Instead of saying an architecture "scales," I can state the expected workload, known bottlenecks, and how jobs are retried.

Numbers are not always required. A reduced permission list, a simpler state transition, or a reproducible failure case can also be evidence.

The point is to show the path from observation to conclusion. Readers can then decide whether the lesson applies to their context.

Edit for the person doing the work

My first drafts often contain background that matters to me but not to the reader. During editing, I ask what someone needs if they are facing this problem today.

Usually they need:

• A clear description of the problem
• The constraints that shaped the solution
• The chosen approach
• A warning about likely failure modes
• A practical next step

They do not need inflated claims or a long summary of concepts they already understand.

I also remove phrases that make the writing sound more certain than the evidence supports. "Always" and "never" are rare in software. Most decisions are conditional, and good writing should preserve those conditions.

Originality comes from specificity

It is difficult to write something useful by starting with a broad topic such as productivity, React performance, or startup lessons. The internet already has thousands of summaries.

A specific project provides material that cannot be copied from a generic outline. The strange CSV input that broke validation, the browser API that behaved differently after an update, or the client workflow that changed the data model can lead to a more honest article.

The lesson may be familiar, but the route to it is personal. That is where an original voice develops.

Publishing creates a useful feedback loop

Code reviews happen inside a project. Public notes invite feedback from people with different constraints.

Sometimes a reader points out a missing edge case. Sometimes they share a simpler approach. Sometimes the article helps a person avoid a mistake I spent hours understanding.

This feedback is not always immediate, and it should not become the only reason to write. The first benefit exists before publishing: the decision is clearer and the project has better documentation.

A sustainable writing workflow

The writing habit that works for me is intentionally small:

1. Capture decisions while building.
2. Choose one decision with a useful lesson.
3. Draft without formatting or promotion in mind.
4. Verify technical claims against the current implementation.
5. Remove anything that does not help the central idea.
6. Publish, then update the note if the lesson changes.

I do not wait until I feel like an authority on the complete subject. I write from direct experience and make the boundaries clear.

The point of these notes

I want this space to be a record of how I build products, not a stream of polished announcements.

Some notes will be deeply technical. Others will cover design, client work, or the uncertainty behind a product decision. The common thread is that each one should contain something learned through doing.

Writing in public has not made engineering easier. It has made my reasoning easier to inspect. That is valuable for readers, collaborators, and my future self.