fd91cf1dfd · 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

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.

@@ -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`