Is this a hot take? It feels like it, but maybe it’s common knowledge in 2024. Or maybe it’s a deranged thought that only makes sense if you’ve used vim regularly for any length of time.
Markdown ends up being my writing tool of choice these days, rapidly replacing Google Docs for most personal stuff. Several years ago, I worked on a decent-sized knowledge base where we used Markdown for article content; moving away from HTML took a lot of pain out of the writing and editing process. I write TTRPG supplements in Homebrewery (which has great theming, and also lets you tinker with CSS as needed) and then export to PDF. I take notes in Obsidian (general writing, sometimes moving into Homebrewery) and Joplin (notes synced to my phone, like shopping lists). It’s not just for posting comments.
Obivously, I’d use Word for something larger and more official like a requirements or design document, but for sheer productivity, you can’t beat it. It’s easier to get and stay in flow state because there’s fewer distractions.
Headings
Good skimmable content makes frequent use of headings. At a certain point this can become overkill, but in moderation, it’s a good way to signal what you’ll find in each block of text.
Back in the olden days, you were taught to write an outline before writing your first draft. With computers, you can outline as you write by using headings. I find being able to switch between those contexts extremely helpful, letting me jump to tasks that are fresh on my mind and put off tasks that might derail me at the moment.
Switching between outlining and writing is the biggest productivity boost for me. No weird hotkeys or having to click around in a toolbar. Need to restructure headers on the fly, moving it up or down? Just add or remove a “#” from a heading. If you’re not ready to flesh out a heading’s content, drop in a “**TODO**” and keep going.
Lists
Lists are also a good way to structure skimmable content. If I’ve written rules or documentation and I’m not using lists, my gut instinct is it’s hard to read and I need to take another pass at it. Lists with descriptive, bolded titles followed by detail text is the gold standard.
Again, it’s easy to write and restructure lists in Markdown. Drop in some dashes, then and add or remove indentation to change the structure. (Now that I think about it, maybe you need to have written Python code to appreciate this.)
If you’ve got control over CSS in the output, it’s easy to adjust the spacing for the entire document. You don’t have to fiddle with arrows on a ruler like you do in Word; you don’t have to fight with weird edge cases where you mix ordered and unordered lists.
Counterexample: Tables
Tables are the biggest weakness I’ve encountered when using Markdown, which is unfortunate since they’re also a great tool for structuring skimmable content. When a list gets too complicated, it probably needs to be a table.
I suspect your tolerance for Markdown tables depends on how you feel about ASCII art (that is: did you use a computer in the 90’s back when we only had 255 characters?).
In theory, a Markdown table should be just as readable in plain text as in formatted output–you build the structure with pipes (|) and dashes (-). Some tools have extensions for centering and spanning rows and columns if necessary, though this is a bit cryptic and I always have to look it up.
In practice, it’s easier to just write out the bare minimum without lining up the plain text–let columns end wherever they will, don’t clean them up. Who cares about plain text readability if you’ve got a preview pane? Still, even the bare minimum can be a distraction. It’s an area where tooling improves the experince–text editors that have automatic formatting will fix tables for you.
But it usually means I don’t add a table until way, way after I realize one is needed.
Using Markdown
All of the applications I mentioned above have side-by-side previews. Most text editors do this (I know it’s available in Visual Studio, Visual Studio Code, and Notepad++). Many have some level of automatic formatting (which, again, takes the pain out of more complicated bits like tables).
Markdown is also pretty extensible. Homebrewery has built-in support for boxed descriptive text and sidebars, as well as some more complex templates straight out of the D&D Player’s Handbook. For me, being able to drop in multiple types of sidebars rapidly has helped my organization–putting a box around important notes or rule text feels like it drastically increases readability. If I was writing in plain text or Word, I’d never think about that being an option; if I was writing in HTML, typing out the div tags would be a distraction.
If you can’t find the formatting you need, there might be an extension that handles it. (However, one of the benefits of writing in Markdown is you’re mostly limited to simple stuff like bold, italic, and underline–there’s less risk of creating more complicated formatting that’s hard to standardize across your document.)
Finally, if you’re writing content for use in an application (help text, etc.), it’s actually pretty straightforward to parse Markdown into HTML. There’s multiple libraries out there for different languages and use cases; some even have the ability to add your own extensions. For example, in the knowledge base project I referenced at the top of the post, I added syntax to create expandable/collapsible text blocks in content, which greatly simplified building the page structure we were going for.
If you want to give it a shot, it’s fairly easy to get started:
- Homebrewery is a great way to jump right in, if you’re writing something that fits in a two-column layout (though Firefox has some rendering issues). Right now you’re limited to fantasy-style themes by default, but they recently introduced a theme selection so that may change at some point. (I’ve also been keeping a library of themes.)
- Obsidian is a great choice for larger collections of information. I keep all my vaults synced with Google Drive since they’re just folders and text files. Being able to build out folders on the fly is incredibly helpful for feeling out what organization works best; I find it way easier than specialized tools (such as World Anvil for TTRPG content) that tend to lock you into specific structures.