cmc/cleberg.net

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