I could not disagree more. I'm very pleased that things such as markdown exist and are being widely used. All of the tools used by 'other professions' as you say, are in some nonsense proprietary format that works in their application and theirs alone. Even something as widespread as .docx is still a third-class citizen on other applications, due to Microsoft's monopoly on it.
Is Markdown perfect? No. I find it rather frustrating that there isn't a single definitive flavor, but it's easy to learn, easy to read and render, and can be used as a tool in just about anything. You can keep your 'real programs'.
I really don’t understand what they think we’re missing in markdown, as if most of us don’t have plenty of experience with “better “ document software. They also don’t actually explain what features or tools make that’s software “better.” Most people I know in these trades are using Google or Office suites simply because that’s what they’re the most familiar with.
I’ve been through so many formats and styles of capturing information and always come back to markdown. If OP has specific critiques of what we’re missing out on, I’d love to hear them. Mostly it was just vague ranting about “devs love old tech.”
Markdown mixes formatting and content (in a lossy way - did the author mean that asterisk as a format character or as part of their text? Who knows). It doesn’t support spans or ranges for mixing languages. It has hard-to-remember syntax, especially around links - Gruber makes mistakes with it all the time. And it doesn’t easily support the sort of powerful visual editing tools like you might have seen on a 1980s Mac. And worst of all, developers think it’s “good enough” and ship it to non-developer users instead of making them actually powerful tools for managing text.
1. Mixing formatting and content is the point. Maybe it’s not for you, but describing its main feature as a problem doesn’t make sense.
2. There are maybe 5-10 syntax elements to get up and running with Markdown. Your average excel user has probably committed far more keyboard shortcuts to memory.
3. Most markdown users are fine with importing an image from another app if “powerful visual editing tools” (which still haven’t been defined) are needed. Not to mention extra features in this area provided by Markdown editors like Obsidian.
4. Again, I still don’t know what you consider to be an “actual powerful tool” for managing text. Does your definition begin and end at WYSIWYG?
1. Right, but unless you want a circular argument, the “better” you are missing is the ability to separate the two. You should be able to type a note featuring all the characters on the keyboard without unexpected side-effects, this doesn’t seem like a lot to ask.
2. And yet the inventor of the thing repeatedly gets it wrong.
3. Visual editing here meaning more WYSIWYG than the inclusion of images, but it raises a good point - the bounds of what we consider a document is rapidly outstripping what markdown can comfortably capture. Tools like Notion are blurring the line between what used to be thought of as “text” and “embed” and are making great user experiences by doing so.
4. Honestly, in this context (document editing) I think of ClarisWorks as a more powerful tool than any Markdown editor I’ve ever seen.
A ClarisWorks with Obsidian-like features would be a rocket ship for the mind. Limiting Obsidian to Markdown is like using diesel to fuel the rocket.
One of my highest priorities for a personal knowledgebase is that my system can continue to be essentially unchanged for the rest of my life (hopefully another 50+ years), just as my current archive of notes goes back 20 years.
The Lindy Effect[0] would say that plain text files have already existed for more than 50 years, therefore are likely to still exist another 50 years from now.
That being said the Obsidian team are making progress towards adding WYSIWYG, so you will soon be able to edit visually while keeping the files stored in a readable plain text format.
There are a lot of tradeoffs to using non-plaintext formats beyond not being able to edit them on old-school green CRTs:
- Have you ever tried using git on a docx file? The best you have is file history, but good luck trying to merge branches, create/apply patches, cherry-pick commits, rebase, or view line-by-line history.
- You lose the interoperability of plaintext. Any editor can open a plaintext file, and consuming a plaintext file is straightforward. Not so with binary.
- You lose a lot of choice about how you want to interact with the file. Syntax highlighting, TextMate bundles/snippets, and hundreds of editors and plugins are available to both create and consume Markdown (and many other text formats).
I agree that rich text editing is great, but may I suggest looking into another plaintext format besides Markdown if you can't find a wysiwyg markdown editor you like? There's RTF, TeX, and others -- each with a great ecosystem of tools around it.
More generally, if a particular plaintext format doesn't meet your needs, I'd argue the problem isn't necessarily that the format is plaintext as opposed to binary. Binary can be nice for serializing C/C++/etc. objects and for packaging resources, but there are tradeoffs.
You are begging the question. Git works well with plaintext because it is a product of the 1970s thinking that OP is bemoaning. If we built tools to do Git-like things on rich text file formats, they’d work just as well. (And Track Changes does a subset of those things surprisingly well inside Word, fwiw)
And OP didn’t specify binary output. The output format could be anything we standardised on, just so long as it supports rich editing environments. That is, we shouldn’t have to write in the output format; the two can (and probably should) be disconnected.
Markdown is both a terrible output format and editing experience, especially when you get complicated. It’s the worst of both worlds.
I've been using MS Word with a heavy reliance on Track Changes for years, and I'm converting my technical writing department to use Markdown as fast as I can. I have moved them to the WYSIWYG-on-Markdown editor Zettlr[1], and my non-technical writers have praised it for being "almost-not-techie at all".
I can't stand one more MS magic trick to auto-formatting on copy-paste (while mangling half of the styles) or figuring out why some objects simply disappeared or why Word rejects applying some format or layout.
When your job is to keep working on expanding the same hundred-pages-long document year after year, you learn every trick to fix the random MS Word bugs and protect your document from being destroyed by the software 20 times a day, and it ain't pretty.
* I would have preferred to use Asciidoc instead of Markdown, as it comes with the full Docbook feature set; unfortunately, native support on well-maintained editors is much worse with that format.
Why not try FrameMaker or something actually built for the job, instead of forcing your poor team into a “still-actually-techie” format written to get around the limitations of MovableType for formatting weblogs? You’ll get DocBook support and still be free of the undeniable horror that is Word
What you call question-begging is really just an assumption I'm making - that git's feature set isn't available (or practically feasible) for any binary format.
You might disagree with that assumption, but if so I'd challenge you to show me (or build) a piece of software that (a) uses a binary storage file format and (b) has a feature set comparable to that of git for files in that format.
I know an argument from lack of existence doesn't prove anything. It certainly is within the universe of the possible to implement git's feature set in MS Word. But I highly doubt MS will ever do that, as that wouldn't make sense from a business standpoint.
A great general version control system is most likely to be implemented on formats that are the most interoperable. Nothing is more interoperable than plaintext. Perhaps if someone designs a structured general-use binary format that becomes widely adopted, then version control will be implemented for it. But I bet if someone does try to build such a binary format, someone else will follow it up by building a similar or better plaintext format. Plaintext is more attractive for non-proprietary software, because you get a lot for free.
In fact, I believe the only long-term business benefit of a binary format is vendor lock-in.
You might say developers are spoiled -- we enjoy power and freedom in our workflows that others don't even know is possible. I for one prefer the power and freedom that plaintext formats (both data and code) afford. Although I do sometimes use MS Word, I almost never commit a non-plaintext file to a git repo when there's a plaintext-format alternative.
(Again, rich text doesn’t need a binary file format but you ignored that)
Word’s Track Changes literally does this - you can compare/merge/etc. Quark also had extensions in the 90s that allowed it. It’s entirely feasible for any binary format (assuming you understand the format); why wouldn’t it be?
And it makes a lot of sense from a business standpoint, eg for lawyers, which is why they implemented it. Is it as rich as git? No, the use-case is different. Could it be? Yes.
I’m going to leave “power and freedom” where they lie and go marvel at the awesome power of the “Italic” and “Table” buttons from Word 5.1.
> (Again, rich text doesn’t need a binary file format but you ignored that)
I'm not arguing against rich text. I think it's a great idea. (My earlier comment suggests using it, actually.)
> Word’s Track Changes literally does this - you can compare/merge/etc.
Nice, but it doesn't support cherry-picking, creating and applying patch files, or any distributed VCS features. I'd also venture that it likely doesn't have anything like the 4-pane merge UI that tools like kdiff3 have.
---
If Word covers your needs, great! I'm not sure why you're arguing against markdown in favor of it, though. The two solve different problems.
I'm not arguing against word, just pointing out the practical differences between binary and plaintext files. Use what suits your particular needs!
I think the reason for programmers' attachment to Markdown isn't just about being able to operate on it in a terminal. It's about the general interoperability of plaintext.
Terminal editing is one example, but even IDEs and non-terminal text editors also use plaintext. There's also the fact that version control tools are designed for line-based plaintext. Markdown is especially often used for documentation that gets checked in alongside code, so this is an important consideration.
I would be very interested to hear thoughts on good alternatives to Markdown for technical documentation, even if not plaintext-based.
1000% this. Markdown will be around forever. I'll be able to open an old file 20 years from now, _because_ it's just plain text. That's a feature, not a bug.
I'm so done with tying myself to rent seeking proprietary formats. For something as personal, important, and long lasting as notes / writings, I'll take the minor hit on absolute feature set.
Wow, I couldn't feel more differently about markdown. I'm not a programmer, but I welcome this useful non-proprietary format. I just wish I could get my entire small business to use a Wiki full of markdown files (which present very nicely with wikijs and other such software) instead of a bunch of folders full of MS Word files.
>In fact, the whole programmer's fetish with writing everything with a plain terminal text editor needs to die. Markdown, YAML, JSON, INI files. It's the year 2021 for christ's sake, and we're composing documents with tools designed for green CRTs!
Alternative take for this same sentiment: It's the year 2021, why has nobody figured out better ways to present knowledge than simple text files?
There are better ways [1] [2], there's just no paying customers. You can express knowledge using a Semantic Web Stack[3], encode data in N-Triple/JSON-LD/RDF/XML and query it with SPARQL or Turtle. Wikidata[4] is an example of this.
But (afaik) nobody's selling a product that builds and queries a large semantic knowledge base for consumers. Some industries have Semantic Web-based solutions (i'm not aware of commercial ones but I assume they exist), but nobody has yet explained to the consumer why or how they should build ontologies or keep data in triples. The terminology itself is probably a barrier to market, and all the interfaces are (imo) clunky.
If I were to build a consumer product, I would hide all the technical jibberish and make a slick UI that walks the user through linking semantic data, leaning heavily on Wikidata to fill in gaps. Gameify it so that people can compete for points to link more data, add a subscription fee, add social components: poof! Billion dollar personal-knowledge-base app to replace Evernote. Value add/tagline: "Know yourself better." (inb4 selling the free version's users' anonymized data to advertisers...)
Better technology works like this: some people pioneer in it and most people are skeptical initially. Eventually, almost everyone transfer to using the better technology, and will wonder how they ever coped with the older technology.
I know, we don't get many of these in this field anymore. I think this means something.
Not the OP but I'm happy to defend WYSIWIG editors. Things like font size and bold and italics exist for a reason. Markdown tables are extremely clunky. Inline images (or pretty equations) are important for many types of writing. Bullet lists in markdown more than two levels deep get interpreted as code my most syntax highlighters.
Don't get me wrong, I love plain text and I do most of my writing in markdown, but WYSIWIG editors have their place. As do things like spreadsheets (for represent lots of info) and LaTeX (for docs).
The general problem, of course, with WYSIWIG is distribution: what YOU see might not be what someone you send the document to sees. Do the people you're sharing the document with have the same application, the same version of that application, the same fonts installed? You can export to a presentation format like PDF (or HTML), but then they can't edit it as you did, and it's also likely that the translation will change "what you see".
Markdown is a least common denominator for sure, but that limitation also gives it a useful universality, which is what proponents value in this case.
I don't want to downvote you but I do disagree with most of what you said. Tech writers should be able to learn things and not just be stuck in whatever single tool they are familiar with.
To me, it is clear you don't want to spend minimal effort to understand simple tools because it is not the tool you are familiar with and like to use.
Obsidian is not perfect, but not for reason of using Markdown.
I’m slightly relieved reading this. I see markdown everywhere, I can’t stand it, and I wonder why people are so crazy about it. It’s nice to know I’m not alone.
Unfortunately I don’t think markdown is going anywhere. I think I see it far more than ever and there’s no sign of it slowing down.
I have been sent word documents that I’ve been totally unable to read.
I’ve never been sent a markdown file that I haven’t been able to read.
I’ve been sent a PDF that looks correct, but I’m not able to easily edit. I’ve never been sent a markdown file that I’ve been unable to edit.
For a document format to be able to be widespread it needs to be interoperable and work on all systems. Markdown is popular because plain text works everywhere.
I’m not convinced that markdown is the ultimate format, but it has more good properties than most other available formats.
But "looks correct" for PDF presumes a certain form factor of the device used, because of the fixed page size. PDFs are a pain on many e-readers because they are laid out for US letter or A4 at a certain resolution. On a smaller device I often find I have a choice of either a. seeing an entire page at one time, as intended, but needing a magnifier to read anything, or b. zooming in to be able to read the text comfortably but then having to scroll left/right/up/down to read. There's no option in PDF to reflow the text to fit the resolution and size of the device. I'm not much of a fan of epub but at least the text reflow allows for normal reading.
Also, exporting text from a PDF to import to anything else is trying at best.
I agree with you, markdown is far better than what you’ve described.
It’s an interesting thing to consider. How do we get somewhere sane between markdown and say HTML for example? What would that look like? Can you get the ease of markdown with something that would let us do more too?
I fell in love with Markdown in the early 2010s. My team at work didn't have a corporate wiki, and the only alternative to documentation was network shares and non-searchable folder hierarchies. I installed Dokuwiki, and its editing is all markdown.
The alternative became Confluence, which is now a pretty decent product(for the end user, I can't speak to operating it).
But in 2013, the editor was terrible. WYSIWYG was broken and non-deterministic. You never knew how it was going to try to "intelligently" format your next press of the enter key, or bullet list or table. There was no visual cue on the work it was doing for you.
Markdown is very clear, if limited: There is no ambiguity on how it will format a page.
I will say, I think there are tools that provide WYSIWYG composers that store data in Markdown backend, giving the benefits of both easy editing, and a stable, human-editable source format.
> I can’t stand it, and I wonder why people are so crazy about it.
I wonder why people can't stand it. It's raw material that can be easily be transformed into a plethora of formats, both open and propriety. See e.g. https://pandoc.org/
Agreed. It's a form of jargon, which is effectively never a recommended (communications) tool. If it was the best-fit tool, sure then so be it. But too often the jargon tools are more about being elitist than anything else.
Or maybe I've been at this too long, and too naively still optimistic?
Being a mechanical engineer student myself, I can see where you're coming from, however, I have to respectfully disagree.
It's true, most professionals use off-the-shelf solutions, the Office/Adobe suite, or other proprietary software like Catia, Autodesk, the likes. I have been nothing but frustrated by these options. I have dealt with gigabyte Illustrator files, as the inexperienced user accidentally embeds all linked media. I have been increasingly frustrated with "made up marketting terms" when saving Adobe proprietary formats, or OneNote's "invisible formatting language". I make a new line, then remove it, and whoops, the whole paragraph has been reformatted, all the equations are no longer in italics (despite this, I still use it for all of my study material, it's fantastic)! It helps to have a Markdown-like mental model when dealing with word processors, you understand the data hierarchy, which is at the end of the day underneath all of that GUI, most people I know who use Word make an absolute mess of the document because they have no idea how to have a consisent layout, they add new-lines, paragraphs, tables, fonts and indententations all over the place and then get frustrated when they don't get the desired results.
While Markdown may not be the best format with the most features, it has a fantastically consistent layout and it's easy to understand the hierachy of information. There is no obligation to use the terminal, you can open it in any visual editor. Also, I would not call the fact that it's plain text instead of XML/binary a limitation but rather a feature, not a "remenant of the 1970s".
There is something amazingly refreshing about knowing that what you see is what you get, I can't stress this enough. Instead of using buggy program that manipulates a mess of an XML file, you describe the layout from scratch and that gets "compiled" to a PDF. This is why programmer source code is written as text, and not in Word, for example, it's just plain information that any compiler can work with to achieve any sort of complexity. There is no hidden document metadata, there is no hidden bloat from [insert proprietary software here] having upgraded the document format several times over the years until it eventually corrupts something (I'm looking at you Premiere Pro, every major version requires you to upgrade your saved project, making a new copy "just in case", it's impossible to go back, and I've had it break several times). It's a single source of truth that describes a behaviour, and the compiler can get better over the years and generate better and better executables from that same code as it improves.
This is the worst argument ever, but it's still an important one: it's free, and works on any OS. There are definitely advantages to using off-the-shelf software, I myself am a heavy user, but I cringe every time I have to work on a messy document with other students, recently I had to work with another student that has macOS and could not get Word to open the document and display equations without converting them to images...
I find the Markdown/Word comparison similar to my experience with Docker and Windows, for those that are familiar with it. Windows, macOS and Linux (although Windows is the worst offender) get bogged down with bloat over time, dnagling files, layers of abstraction, derived from complexity. How many times I wish I could start from a base image, and add/remove (software) features as I go, like building a new Docker image, without losing data.
You bring up scientists, granted, not everyone uses it, but I believe LaTeX is more comparble to Markdown than to Word. It has a text-based source format that gets transformed and rendered as a PDF, but it's way, way too complex for the majority of use cases. If there's a better alternative to Markdown, I'd be glad to try it out, but for now it's my main choice for the long-term storage of information.
I'm a programmer, I know Word exists. If someone wants me to produce a Word document, I can take all my content that's in markdown and generate a .docx file. I can also generate dozens of other formats, all from the same raw material https://pandoc.org/demos.html
I haven't yet seen a tool that can take a Word document and transform it as neatly and automatically into many other formats, although it's gotten much better since things like Open Document Format compelled Microsoft to ditch the all-binary .doc format and move to the mixed XML/binary format used now.
In the end, Markdown is a summarized way to write simple HTML; all styling should be done on a separate CSS. If you intermix lots of <div>s with class names in your text, you're not doing Markdown well.
