What Goes in Public Documentation, and What Stays Private

Good technical writing needs detail. Good security practice limits unnecessary disclosure.

Those goals are not opposites. The useful part of a technical article is usually the behavior, the decision, the failure mode, and the validation. The dangerous part is often the accidental context wrapped around those things.

That distinction changed how I write Field Notes.

I now use a simple boundary: information required to understand the lesson can be public; information required to reach, identify, or administer the live environment stays private.

That sounds obvious until you start publishing screenshots, commands, logs, diagrams, and configuration examples. Then the line gets much easier to cross by accident.

Public detail should explain the system

A useful article should still be technically specific.

I am comfortable publishing things like:

• component roles;
• dependency relationships;
• failure symptoms;
• sanitized commands and errors;
• decision criteria;
• validation methods;
• recovery concepts;
• product names when they are essential to the lesson;
• versions when the behavior actually depends on them;
• generic examples that let the reader reproduce the idea in their own environment.

The goal is not to make every article vague. The goal is to remove information that has no teaching value.

For example, saying that an application host mounts storage over NFS is meaningful. That tells the reader something about latency, permissions, dependency order, and failure behavior. Publishing the internal hostname, server address, export name, and exact mount path usually adds nothing to the lesson.

A good public article should let somebody understand what kind of system exists without giving them a map of my specific system.

That is the same reason I separate lessons from environment-specific details in Why I Write Engineering Notes in Public. Public writing becomes more useful when the reader can map the idea onto their own infrastructure instead of reverse-engineering mine.

Operational identifiers stay private

My publication pass specifically looks for values that identify, locate, or administer infrastructure.

That includes:

• hostnames and internal domains;
• public and private IP addresses;
• usernames and email addresses;
• MAC addresses, serial numbers, asset tags, and barcodes;
• wireless names and internal network labels;
• account, tenant, customer, and organization identifiers;
• storage-pool names, share names, and backup destination names;
• management URLs and nonpublic domains;
• tokens, keys, cookies, credentials, and recovery codes;
• exact file paths that expose usernames, project names, or internal structure;
• ticket numbers, case IDs, or other identifiers that tie a public post back to a private system.

Some of those values are obviously sensitive. Others look harmless on their own.

The problem is aggregation.

A hostname reveals a naming convention. A screenshot reveals a subnet. A terminal prompt reveals a username. A browser tab reveals a management product. A storage path reveals the server role. None of those details may be enough by itself to matter. Together, they can describe topology, product choices, physical placement, and likely access paths.

That is why I do not use “it is not a password” as the standard for publication.

The better question is: does this value help the reader, or does it only describe my environment?

If it only describes the environment, it usually does not belong in the article.

Role names are better than real names anyway

There is another benefit to sanitization that has nothing to do with security.

Role names make technical writing clearer.

“Application host,” “storage host,” “gateway,” “database,” and “external client” tell the reader what each system does. Internal nicknames tell the reader what I happened to call a machine.

The role survives hardware replacement. The nickname does not.

That matters because a Field Note should still make sense after the environment changes. If the article depends on one server name, one VLAN label, or one directory tree, then the writing is carrying more implementation detail than it needs.

This is also why my private operational documentation and public documentation have different jobs. I wrote about that split in What Goes in Public Documentation, and What Stays Private. The private record should tell me exactly what exists. The public article should explain why the design mattered.

Screenshots need their own threat review

Screenshots are one of the easiest ways to publish more than you intended.

I do not review only the panel I want readers to see. I look at the whole image.

That means checking:

• browser chrome and open tabs;
• address bars and autocomplete suggestions;
• terminal prompts;
• notification previews;
• account avatars and profile names;
• background windows;
• file names and directory trees;
• network labels;
• clocks and location hints;
• maps, camera views, and physical context;
• reflections and secondary displays;
• image metadata and filenames when they are being distributed directly.

Cropping is useful, but it is not a substitute for review.

If the live interface is not necessary evidence, I would rather create a purpose-built diagram or table. A diagram can show the relationship between a client, gateway, application, and storage layer without accidentally documenting the live admin interface at the same time.

That usually produces a better article too. The reader sees the dependency I am trying to explain instead of spending time decoding my dashboard.

Generic examples should look generic

Sanitized examples should not look like barely redacted production data.

I prefer obvious placeholders, reserved domains such as example.com, role-based names, and documentation-only addressing when an address is actually necessary to explain a concept.

I also try to write clean examples from scratch instead of copying a real configuration and deleting sensitive lines afterward.

That distinction matters.

Redaction asks, “what must I remove?”

A clean example asks, “what does the reader actually need?”

The second question usually produces less clutter and fewer mistakes.

For credentials, the example should explain the injection method, secret store, environment variable, or configuration mechanism without containing anything that resembles a usable token.

For paths, /srv/appdata/example-service communicates far more safely than a real path that includes an account name, project name, or internal mount convention.

Logs and error messages deserve more suspicion than they get

Logs feel technical, so they are easy to treat as inherently safe to publish.

They are not.

A useful error line can sit beside:

• a real hostname;
• a user ID;
• a filesystem path;
• a private address;
• an account or tenant identifier;
• a URL with a token in the query string;
• a certificate subject;
• an email address;
• an API response that includes IDs unrelated to the failure.

When I need a log excerpt, I keep the smallest section that proves the point and normalize the identifiers around it.

The objective is evidence, not transcript preservation.

That same evidence-first mindset is useful in troubleshooting generally. The Test Matrix I Use Before I Trust a Change is built around the same idea: preserve enough information to prove the result without confusing volume with quality.

Repository history changes the risk calculation

Publishing through Git means deletion is not the same thing as erasure.

If I accidentally commit a hostname or internal path and remove it in the next commit, the public page may be clean while the repository history still contains the original value.

That changes my process.

I try to sanitize before the first publication commit rather than relying on a cleanup commit afterward.

For ordinary identifiers, a later cleanup is inconvenient. For credentials, the response is stronger: rotate or revoke the secret and treat the exposed value as compromised. Editing history is not a substitute for invalidating something that may already have been copied.

This is why the publication review happens before the draft moves out of the backlog.

Private documentation still needs real controls

“Keep it private” is not a complete security model.

Operational documentation can contain exactly the information I remove from public articles: exact addresses, recovery procedures, account ownership, backup locations, and management paths.

That makes the private copy more sensitive, not less important.

It needs appropriate access control, encryption where warranted, backups, retention decisions, and ownership. Secrets should live in a credential system rather than being scattered through a runbook just because the runbook itself is private.

Sensitive screenshots and captures should also have a reason to exist and a reason to be retained.

The public/private boundary reduces unnecessary exposure. It does not excuse weak handling on the private side.

My final publication pass is deliberately boring

The last review is not creative work. That is the point.

Before a technical draft leaves the queue, I search the text and filenames, inspect linked assets, review code blocks and comments, and look for identifiers that survived earlier edits.

I check whether generic replacements introduced contradictions. If a diagram says storage-host but a command still references a real server name, the article is not sanitized just because most of it is.

I also ask one question about every environment-specific detail:

Does the reader need this value to understand or reproduce the lesson?

If the answer is no, I remove it.

That is a much better standard than trying to decide whether every individual value is technically secret.

Useful documentation should reveal the lesson, not the environment

I want Field Notes to be concrete enough that somebody can learn from the work.

I do not need them to be a public inventory.

The strongest version of a technical article keeps the architecture, reasoning, failure mode, commands, validation, and recovery lessons that make the work reusable. It strips away the identifiers that only make the article specific to one network, one account, or one machine.

That boundary improves security, but it also improves the writing.

The article becomes less about my exact setup and more about the part worth carrying into the next one.

If you are maintaining a large writing queue, A Backlog Is Not Finished Until the Ideas Are Distinct explains the editorial side of that process. Distinct articles need distinct jobs, and a proper privacy pass is part of deciding whether a draft is actually ready to leave the queue.

Consolidation note: This retained article now includes the distinct operational material from the earlier Field Note that covered the same reader intent.

Private notes optimize for recovery

When a service fails, I need exact answers.

The private record may include:

• System roles and internal names
• Network and management addresses
• Exact storage exports and mount points
• Service accounts and numeric identities
• Backup locations and recovery order
• Certificate and domain dependencies
• Configuration repository paths
• Links to protected credential systems

That information belongs behind appropriate access controls. Removing it would make the recovery document less useful.

The document also needs an owner, a review trigger, and a known location. A perfect runbook that I cannot find during an outage is not operational documentation.

Screenshots need their own review

Text is easier to search than pixels, which makes screenshots deceptively risky.

I review the entire frame, including:

• Browser tabs and history suggestions
• Address bars and bookmarks
• Device labels and account avatars
• Notification previews
• Serial numbers and barcodes
• Wireless names and client lists
• Terminal prompts and working directories
• Background windows and second-monitor content

Cropping is often safer than blurring because blurred text can remain partially readable. A purpose-built diagram is safer still when the live interface adds no essential evidence.

This is one reason the definitive guides use sanitized diagrams instead of screenshots from the live environment. The diagram can show the dependency or traffic flow without quietly publishing the inventory behind it.

Documentation decay affects both audiences

Private notes become dangerous when paths, accounts, or recovery steps change. Public notes become misleading when software behavior or supported versions change.

I record what should trigger a review:

• A host migration
• A storage or mount change
• A major application upgrade
• An authentication or remote-access change
• A backup redesign
• A failed recovery attempt
• A public article that reveals an assumption the private notes no longer support

Not every document needs a calendar reminder, but every important one needs a reason to be revisited.

AI transparency

AI assisted with organizing and editing this article. The publication boundary and checklist come from sanitizing technical drafts, screenshots, examples, and operational notes before publication.