101–110 of 328 posts
If what is to communicate, plain text is good enough. If you want to control how information is consumed, fuck of, die already.
Earlier quoted context omitted.
Worse is better doesn’t mean worst is best either.
Markdown is pretty far from the worst. It's decent and unobtrusive. Worst would be something like Troff or jira formatting. Midtier would be RST.
I've written over a dozen books. Have used asciidoc, HTML, word, latex, and rst. Markdown is the least painful of all. It's not perfect but the others are worse. (My custom stack uses markdown (or Jupyter notebooks converted to markdown). Pandoc plus some custom filters creates typst (for PDF) or epub.)
Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/Worse_is_better - and perfect is the enemy of "good enough." We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough! Markup is overhead. Complex markup is even more overhead. Markdown is the…
Earlier quoted context omitted.
"Better specified" doesn't mean better. A bunch of features doesn't mean better. Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style. Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare…
Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc. Bonus: It starts simple but can be used to do whole books if needed.
If you introduce something with advanced functionality onto a team, soon enough someone's going to use pieces that others don't fully understand later.
Now everyone touching the document has to understand includes and document metadata and whatever else someone added. Suddenly you have includes and cross-references and what used to be a document where you could read the raw non-rendered form linearly top to bottom is a confusing mess unless you render it. Markdown is almost always just as legible raw as rendered.
Earlier quoted context omitted.
"Better specified" doesn't mean better. A bunch of features doesn't mean better. Markdown is popular because it is simple. I have never had to teach anyone Markdown. They look at the file and immediately see what's going on and can copy the style. Occasionally someone may have to look up something like table syntax, but no one in my career or personal life has ever asked me to explain Markdown to them, which is rare…
Have you tried Asciidoc though? It is, IMHO, much clearer than markdown (YMMV, obviously), and exactly the same pros you gave of markdown can be said of Asciidoc. Bonus: It starts simple but can be used to do whole books if needed.
Earlier quoted context omitted.
Not wrong, perhaps a little weird. HTML is a first class citizen in the commonmark (spec)[ https://spec.commonmark.org/0.31.2/#html-blocks ].
"Wrong" does not necessarily mean "against the standard". It means "against common usage and good team practice" in this context. It's "allowed" to use raw pointers, malloc, and any number of things in C++ code. In general, if you do any of them in a modern codebase you're doing it wrong.
##[color:red] Heading 2
or using code blocks with particular headers which render out as normal text with the styling applied, like this:
```styling: 'ruleset here...' Lorem Ipsum Dolor ```
this does require a lot of work to consider what might be ergonomic for a particular element (by element I mean ATX headings, blocks, etc.), though.