Why I Write Engineering Notes in Public

Private notes help me recover the command. Public notes force me to explain why the command belonged there in the first place.

I started Field Notes because I was already documenting things.

Just not very well.

The useful parts of a project would end up scattered across terminal history, screenshots, temporary text files, browser tabs, half-finished diagrams, and whatever I could still remember after the problem stopped being urgent. That was often enough to finish the work in front of me.

It was rarely enough to explain the decision later.

Worse, the notes were usually written for an audience of one person at one moment: me, while I still remembered the context.

Publishing changed the standard.

A public engineering note has to survive questions that a private reminder can avoid. What actually happened? Which conclusion is supported by evidence? Which parts of the configuration are essential to the lesson? Which details only identify my environment? What did I test, and what am I merely assuming because the final result worked?

That extra pressure has made Field Notes useful to me in a way I did not expect.

The writing is public, but the biggest improvement happens before I publish anything.

Completed work comes first

I do not want Field Notes to become a museum of projects I might build someday.

Ideas have value. Planning documents have value. Architecture sketches absolutely have value.

They are not the same thing as an engineering note written after the system has pushed back.

For most posts, I want one of three things underneath the article:

work I actually completed,
a failure I actually observed, or
a decision I can explain after living with the result.

That rule prevents a very easy kind of technical writing: describing the clean version of a system before reality has had a chance to ruin the diagram.

Real implementations acquire exceptions. Dependencies fail in inconvenient orders. A service that looked independent turns out to need a mount, a credential source, a DNS answer, and a device that nobody drew on the first architecture diagram.

Those are usually the useful parts.

When I wrote When an Empty Mount Looked Like an Empty Library, the lesson was not simply that a mount can fail. The useful lesson was that a directory existing does not prove the expected filesystem is mounted there, and that an application can produce a convincing higher-layer symptom while the real failure sits underneath it.

That is difficult to write convincingly as a hypothetical.

It is much easier after the failure has forced the distinction into view.

An unresolved incident can still be worth documenting, but it has to remain unresolved on the page. A clean ending is not worth inventing.

Evidence has to survive the story

Troubleshooting creates narratives very quickly.

I changed a setting, restarted something, and the service worked. Therefore the setting fixed it.

Maybe.

If I changed three things before the restart, I do not actually know which one mattered. If a port test succeeded, I proved reachability at that point in the path; I did not prove that the application protocol, authentication, storage dependency, or end-to-end workflow was healthy.

Writing the article forces me to notice those gaps.

That has changed the notes I take while I am working. I try to keep enough evidence to reconstruct the sequence later:

Evidence	What I want from it
Error text	The actual failure, not my memory of it
Before/after behavior	Whether a change produced an observable difference
Timestamps	Enough ordering to reconstruct the incident
Narrow tests	Proof about one layer rather than a vague “it works”
Configuration decisions	Why I chose the change, not only what I typed
Validation	Evidence that the original requirement works again

I do not need to publish all of that evidence.

I need enough of it privately that the public conclusion does not depend on memory alone.

That same principle is why I keep coming back to validation in articles like The Test Matrix I Use Before I Trust a Change. A successful command is not always the same thing as a successful outcome.

The article should preserve that distinction.

Public documentation is a second documentation layer

My private operational documentation and a Field Notes article should not contain the same information.

That is deliberate.

Private documentation may need the exact hostname, address, account, path, storage location, recovery procedure, or device identifier required to operate the environment. Those details can be necessary internally while adding almost nothing to the public explanation.

So I treat publication as a translation step.

The private note might say:

media application -> exact mount -> exact storage export -> exact host

The public article can usually say:

application -> mounted storage dependency -> storage host

The second version preserves the relationship that matters without publishing the identifiers that make the first version operationally useful.

That is not vagueness for its own sake.

In many cases, removing the names makes the article better.

“Application host,” “storage host,” “management network,” and “backup target” describe roles. A personal hostname describes one machine in one environment. The role travels better.

That same thinking shaped The Storage Host Became a Contract, Not Just a Server. The durable idea is not what I named a machine or dataset. It is that consumers depend on a storage contract with ownership, permissions, availability, and recovery expectations.

Public writing should keep the contract and discard the trivia.

My redaction pass is part of the editorial pass

I do not consider a draft ready because the prose reads well.

Before publication, I deliberately look for details that can leak through ordinary technical writing.

That includes the obvious things:

credentials, tokens, private keys, cookies, and recovery material,
public or private IP addresses,
hostnames and internal domain names,
usernames, email addresses, and account identifiers,
serial numbers, MAC addresses, barcodes, and license information,
exact storage names, mount points, internal paths, and management URLs.

It also includes less obvious context.

A screenshot can expose browser tabs, bookmarks, file names, device labels, notifications, usernames, or an admin URL that the article never mentions in text. A copied terminal block can contain a shell prompt with a username and hostname. A config example can preserve an internal path simply because I copied the working version instead of rebuilding the example from scratch.

Even realistic placeholders deserve scrutiny. If an example looks enough like a real secret that a reader cannot tell the difference, it is a bad example.

The safest public example is usually a deliberately generic one written for the article, not a lightly edited copy of production configuration.

Redaction should remove identifiers, not the useful failure

There is a bad version of sanitization where everything becomes so generic that the article stops teaching anything.

I do not want that either.

The goal is to remove identity while preserving structure.

If a network problem depended on traffic crossing two policy boundaries, that relationship matters. The exact subnets probably do not.

If a container depended on a bind-mounted path, that dependency matters. My actual filesystem layout probably does not.

If a recovery process failed because the backup shared a failure domain with the primary system, the topology matters. The machine names do not.

This is the distinction I try to make on every pass:

Would changing this identifier change the lesson?

If the answer is no, the identifier probably does not belong in the article.

If the answer is yes, I need to explain the underlying property instead of simply publishing the real value.

That is a much stronger editorial test than searching for a few obvious secret strings at the end.

Cross-linking is how the notes become a system

One article rarely contains the entire idea.

A storage failure can connect to service admission, application-host design, backup strategy, and change validation. A Windows repair article can connect to evidence preservation, standardization, and repeatable checklists.

I use cross-links because the lessons are more useful as a graph than as a pile of isolated posts.

That also keeps me from rewriting the same explanation every time. If one article already establishes why I separate application compute from authoritative storage, a later article can link to The Application Host Is Replaceable on Purpose and spend its space on the new failure instead.

The site becomes a record of how the operating model developed.

That matters more to me than making every post pretend it appeared from nowhere.

The backlog is allowed to lose

A draft existing does not mean it deserves to be published.

Some drafts are useful only as raw material. Some overlap a better article written later. Some were based on a project that changed direction before I had enough evidence. Some contain a decent idea but not enough substance to justify another post.

I would rather leave one in the backlog than publish filler to satisfy a schedule.

The standard I use now is simple:

Did the work actually happen?
Can I support the conclusion with what I observed?
Does the article teach something beyond my exact configuration?
Can I explain the architecture without publishing sensitive identifiers?
Does this add something that an existing article does not already cover better?

If one of those answers is no, the draft needs more work or it needs to stay unpublished.

That is also why I keep drafts physically separated from published content, a workflow I documented in How I Kept Drafts Out of Astro Production Builds. Editorial readiness and build inclusion should not be the same decision.

Writing in public changed how I work in private

This is the part I did not expect when I started the site.

Publishing has made me more careful before I ever open the editor.

I document the original requirement more clearly. I capture the actual error instead of paraphrasing it. I change fewer variables at once when I can. I validate the outcome instead of stopping at the first green status. I think about which details are architecture and which details are merely identifiers.

That improves the technical work even if nobody reads the article.

Field Notes is public-facing documentation, but it functions as a pressure test for my own process.

If I cannot explain what happened without leaning on hidden context, I probably do not understand the incident as well as I thought. If I cannot remove the sensitive details without destroying the lesson, I probably have not separated the lesson from the environment yet.

That is the standard I want the site to keep imposing on me.

Not perfect projects. Not perfect hindsight.

Just completed work, evidence strong enough to defend the conclusion, and enough restraint to publish the lesson without publishing the infrastructure along with it.

AI transparency

AI assisted with organizing and editing this article. The editorial rules, redaction process, examples, and conclusions are grounded in the technical work and publication workflow behind Eldritch IT Field Notes.