What you Say is What you Mean
17 Jan 2025 - Jason Schlesinger
What You Say Is What You Mean
Computers are “dumb”.
There’s noting wrong with that, they are machines that do exactly what they are told. However, interfacing with them can be incredibly frustrating. One of the biggest sources of frustration for many computer users is simply formatting. This frustration goes back as long as computers have been able to output more than just text on a screen.
When you make a change, you want the action to be intuitive, the result to be obvious, and the change to be limited to what you want. If you’re lucky, you get two out of three.
Don’t Be Silly
On one end of the spectrum of editing documents is programming the computer to produce the exact output you want. It seems silly to expect a computer user to have to program any time they want to create a new document. Some people work like this, since you get control over everything. If you’re making a website that needs to dynamically render on a million devices, it might make sense.
On the other end is a “What you see is what you get” (WYSIWYG) document editor, such as Microsoft Word. You don’t need to know how to program, but you then rely heavily on the assumptions made by the editor. Lately, editors are “tricking” users to provide metadata, like section markers, to help with formatting. However, then you’re dipping your toe into programming without geeing the benefits.
Programming Is Silly
Most documents someone will be damn similar to each other. So, why all this fuss about formatting to begin with?
Consider:
- Formatting separate from your document
- Deferring formatting to after editing
- Only needing formatting “hints” to accomplish your goals
- Reducing the time spent fussing over formatting minutiae.
Your Document Dream Team: LyX, Markdown, and Pandoc
There are tools out there that can prevent you from being silly, LyX, Markdown, and Pandoc can all help avoid formatting frustration in one way or another. The downside is that there is some learning curve, but they are incredibly helpful to where I would say it is worth the effort.
LyX
Somewhere between explicitly telling the computer everything you want, and Microsoft Word guessing for you, is LyX The Document Processor.
LyX will let you just dump in text and formatting without needing to think about it 90% of the time. Then, when you need to explicitly describe what’s happening, you can look up how to do it and tell it what you mean.
Your text is stored separately from how it is formatted, which gives you a few superpowers:
- Purpose-built formatting – format for editing, reviewing, and drafting before reformatting for publishing.
- Document-wide formatting changes – apply formatting changes to an entire document in a configuration
- Formatting is explicit and separate from text – you can just read your text as text
Markdown
After the Internet matured somewhat, some people realized “we’re creating whole markup documents to accomplish the same thing.” So they created markdown to simplify creating lightly formatted blocks of text.
This post is written using Markdown, and the raw version of this document is highly readable. It is rendered into HTML using jekyll, and formatted using CSS. This keeps formatting and editing entirely separate, and can be re-rendered using any Markdown rendering engine.
For most text on the Internet, it makes the most sense to use Markdown and walk away from being overly “fancy.” You write what you want, and you can leave the fancy stuff for another time.
Pandoc
So, you wrote your LyX, Markdown, or HTML document, but you need to share it as a PDF or .doc or other file. Pandoc is your one stop shop to turn almost any document format into almost any other.
If you’re coming from a background of Office software, it may seem odd, but you can just turn your collection of formatting instructions and text into something normal people can read. The idea is that you provide Pandoc your document file as you wrote it, and it provides you a document that is easily read.
Perspective Shift
WYSIWYG editors limit your imagination while also being proscriptive about how you and your audience read your content. What’s more is that they force you to consider all aspects of writing as happening concurrently. Furthermore, it implies that what you write and how it is formatted are somehow linked, which is less true now than it ever has been.
Reader Mode
If you’ve used Firefox, you may have noticed “Reader View” in your address bar. Clicking this tells the browser to ignore the formatting instructions from the HTML, and parse the page into something pleasanter to read. Consider that: text passed to the user in a way they want. But what if the user cannot see at all?
Reader mode is an important accessibility tool, along with its big brother: screen readers. If your document is written in WYSIWYM, then you can easily export it in a way that is formatted for screen readers.
- And mobile
- and e-readers
- and dumb phones
- and posters
- and magazines
- etc.