Commit `fd91cf1dfd`

fd91cf1dfd5d280419bbe04b278a99254ec52f8b

parent: 5b184d09bd

Verified · cmc

cmc <hello@cleberg.net> · 2026-05-13 19:28 UTC

publish: plain.org

Layout: unified · split

content/blog/2026-05-13-plain.org added +202

		@@ -0,0 +1,202 @@
	1	#+date: [2026-05-13 Wed 13:03:00]
	2	#+title: Plain Text, Plain Language
	3	#+description: If the file is portable but the writing is opaque, you only solved half the problem.
	4	#+slug: plain
	5	#+filetags: :emacs:writing:
	6
	7	* Plain Text Won
	8
	9	There has been a battle around how to format and store text since computers were
	10	invented.
	11
	12	As computers moved to a more consumer-facing market, developers faced the
	13	challenge of determining the best way to store text. Early consumer software
	14	such as WordStar, WordPerfect, and Microsoft Word implemented proprietary
	15	document formats and rich-text systems, including binary word processor files
	16	and later formats such as RTF, to let users style, print, and exchange
	17	documents. These tools made sense for office work, but they also moved writing
	18	further away from the simplest representation of text: characters in a file.
	19
	20	Plain text never disappeared. It remained the foundation of source code, logs,
	21	configuration files, email, data formats, documentation, and the web. Now, with
	22	the rise of LLMs and agentic workflows, it feels even more obvious that plain
	23	text has won. Corporations may still save Word documents, share PowerPoints, and
	24	use other formats, but they are increasingly turning around and using agents to
	25	extract, summarize, transform, and rewrite that same content as Markdown or some
	26	other plain-text-adjacent format.
	27
	28	Whether another format is used somewhere along the way, the center of gravity is
	29	moving back toward text that can be read, searched, copied, diffed, transformed,
	30	and understood without specialized software.
	31
	32	* Optimizing for Usability
	33
	34	Great, Christian believes plain text won. So what?
	35
	36	Let's think about /why/ we store documents and text.
	37
	38	For personal reasons, we may take notes, write stories and poems, send emails
	39	and messages of other types, post online, and any number of other reasons. For
	40	work, we do largely the same as we do personally, but we also create
	41	presentations, documents, memos, letters, notices, manuals, documentation, and
	42	other artifacts specific to our jobs. Doctors write prescriptions, architects
	43	create plans, auditors create working papers and reports, and so on.
	44
	45	Think about each of these and then imagine that each was produced by Word or
	46	another piece of software where the document can only be opened in that specific
	47	application. If you don't have access to the same application, whether due to
	48	cost, sanctions, licensing, operating system support, or another reason, you're
	49	effectively banned from ever viewing that document, even if it's expressly
	50	intended for you.
	51
	52	In contrast, a plain text document is accessible on every major platform
	53	available today. Modern browsers can open plain text files directly, depending
	54	on the file extension and browser settings, and desktop, server, and mobile
	55	operating systems are capable of opening these files with bundled editors or
	56	viewers. You don't have to install a separate application, accept a vendor's
	57	terms, or hope the original software still exists. You can open the file and
	58	read the content, even if lightweight markup has been applied to it.
	59
	60	** Plain Text Markup
	61
	62	More specifically, I want to talk about a few options beyond literal plain text.
	63	There are numerous markup languages that provide structure and formatting while
	64	remaining readable as text, but a few sit at the top.
	65
	66	1. [[https://orgmode.org][Org Mode]]: Org is my personal favorite. While you need Emacs to experience the
	67	full functionality of Org's interactive components, Org files remain readable
	68	outside of Emacs because the syntax is still plain text.
	69	2. [[https://daringfireball.net/projects/markdown/][Markdown]]: Markdown is the dominant lightweight markup language. It is used
	70	across AI tools, social media, documentation platforms, static site
	71	generators, and note-taking apps.
	72	3. [[https://en.wikipedia.org/wiki/TeX][TeX]]: When you need a language that can handle advanced formatting
	73	requirements, such as mathematical expressions or chemical notation, TeX is
	74	the obvious choice.
	75
	76	These languages introduce additional characters into a plain text document, but
	77	they do not usually detract from the readability of the document itself. They
	78	create documents that can be read directly for quick understanding or rendered
	79	by software that understands the markup syntax.
	80
	81	* Plain Language
	82
	83	Great, we've established the benefits of plain text and optional markup, but
	84	that's only half of the battle.
	85
	86	A file can be open and still be opaque. I don't want to open your plain text
	87	document and struggle to understand the message.
	88
	89	It is entirely possible to write a Markdown document that is portable, durable,
	90	grep-able, and miserable to read. The format can be simple while the writing
	91	remains vague, dense, passive, or full of unexplained jargon.
	92
	93	That is where plain language matters.
	94
	95	Plain language is not simplistic language. It does not mean avoiding technical
	96	terms, removing nuance, or writing for the lowest possible reading level. It
	97	means writing so the intended reader can understand the point without doing
	98	unnecessary work.
	99
	100	In practice, that means:
	101
	102	1. Use the simplest word that accurately communicates the idea.
	103	2. Prefer direct sentences over inflated ones.
	104	3. Define terms when the audience may not know them.
	105	4. Put the main point before the supporting detail.
	106	5. Avoid passive voice when the actor matters.
	107	6. Remove filler that does not change the meaning.
	108
	109	The same reasons I prefer plain text apply to plain language. Plain text removes
	110	technical friction. Plain language removes cognitive friction.
	111
	112	A proprietary document format can make content harder to open. Bad writing can
	113	make content harder to use.
	114
	115	** Plain Text Without Plain Language
	116
	117	Plain text gives you portability. It does not automatically give you clarity.
	118
	119	A =README= can be written in Markdown and still fail to explain what the project
	120	does. A runbook can be stored in Git and still assume tribal knowledge. An audit
	121	workpaper can be easy to archive and still fail to explain the conclusion. A
	122	policy can be available to every employee and still be written in a way that
	123	discourages anyone from reading it.
	124
	125	Have you ever read through a document or standard that is obviously meant to be
	126	accessible technologically and yet, you get nothing out of it? You could re-read
	127	it numerous times and never get an answer because the author was not focused on
	128	accessible language.
	129
	130	The file is accessible, but the meaning is not, and that matters a lot. A
	131	document is not useful because it exists in an open format. It is useful when
	132	someone can read it, understand it, and act on it.
	133
	134	** Plain Language Is Not Anti-Technical
	135
	136	Plain language does not mean removing technical precision. Sometimes the
	137	technical term is the clearest term.
	138
	139	For example, this is vague:
	140
	141	#+begin_quote
	142	The authentication subsystem exhibited anomalous behavior resulting in downstream
	143	workflow degradation.
	144	#+end_quote
	145
	146	This is clearer:
	147
	148	#+begin_quote
	149	Login failed for some users, which blocked deployments that required approval.
	150	#+end_quote
	151
	152	This is still technical, but plain:
	153
	154	#+begin_quote
	155	The CI runner could not authenticate to the package registry because the token
	156	expired.
	157	#+end_quote
	158
	159	The goal is not to make everything casual. The goal is to make the writing carry
	160	the meaning directly.
	161
	162	** The Same Argument
	163
	164	The argument for plain text and the argument for plain language are the same
	165	argument applied at different layers.
	166
	167	\| Plain text value \| Plain language equivalent \|
	168	\|-----------------------+---------------------------\|
	169	\| No proprietary format \| No proprietary vocabulary \|
	170	\| Easy to inspect \| Easy to understand \|
	171	\| Works anywhere \| Works for more readers \|
	172	\| Minimal tooling \| Minimal friction \|
	173	\| Long-term durable \| Long-term interpretable \|
	174	\| Easy to transform \| Easy to act on \|
	175
	176	Plain text is the storage layer and plain language is the interface. Or, said
	177	more /plainly/, plain text and plain language should depend on each other and
	178	neither should be ignored.
	179
	180	If the format is portable but the writing is opaque, you only solved half the
	181	problem.
	182
	183	* Conclusion
	184
	185	Plain text gives information a longer life. It makes writing easier to store,
	186	move, search, version, inspect, and transform.
	187
	188	But plain text does not guarantee useful writing. You can put bad prose in a
	189	good format. You can store unclear decisions in Markdown. You can preserve vague
	190	notes forever. You can make a document technically accessible while leaving it
	191	practically unreadable.
	192
	193	(Have you ever read a README clearly written by AI without any editing from the
	194	repository owner? It can quickly become nonsense as the AI tries to constrain
	195	its content to the best possible README standard, while it loses any meaning of
	196	the project itself.)
	197
	198	That is why plain language belongs in the same conversation.
	199
	200	If the goal is durable, useful communication, the format and the writing have to
	201	serve the same purpose. Plain text keeps the document accessible. Plain language
	202	keeps the meaning accessible.

Commit fd91cf1dfd

Commit `fd91cf1dfd`