Markdown is holding you back
newsletter.bphogan.com
Markdown is holding you back
1–10 of 194 posts
Re: Markdown is holding you back
#2It's interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!
Re: Markdown is holding you back
#3> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices.
This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain in order to re-create 'the semantic web' - a flawed concept that has failed to catch on.
If the LLM needs context on content that humans don't need, the LLM needs fixing, not the content.
> With Markdown as your source, you can't easily go to another format.
File->Print->PDF.
Was that hard? (I admit it's still bizarre that Chrome puts 'Save As PDF' under Print).
(Apparently you can also go via LaTeX if you love a CLI)
Re: Markdown is holding you back
#4Markdown won. Simplicity always wins. Markdown is now the de facto documentation format, for better or for worse.
Re: Markdown is holding you back
#5Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great.
For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me.
But in the end, no markup language will make you write better. It’s kind of like saying that ballpoint pens are limiting your writing, so you should switch to mechanical pencils.
Re: Markdown is holding you back
#6This article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.
Re: Markdown is holding you back
#7> Markdown Lacks the Structure You Need
I feel like this article makes a lot of valid observations, but then wraps them with a false dilemma.
If it had tried to convince the reader of understanding what formatting needs are required before choosing a format, I would have entirely agreed with it.
Instead I'm left feeling mildly offended, and disagree with it.
Re: Markdown is holding you back
#8> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices. This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about sem…
[deleted]
Re: Markdown is holding you back
#9> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices. This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about sem…
> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain
AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended for LLMs is a side effect of that.
Re: Markdown is holding you back
#10You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this.
So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't.
[0]: https://daringfireball.net/projects/markdown/syntax#html