7 ms·
Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/Worse_is_better https://en.wikipedia.org/wiki/Worse_is_better - and perfect is t
by otterley 7mo ago
Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/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 best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.
- wisemanwillhear 7mo agoThe solution is sufficiently perfected with markdown. Just like new revolutionary technologies doesn't replace wheel technology.
- SoftTalker 7mo agoTo actually manage notes and information in plain text I like org-mode markup. For just writing, markdown is good enough.
- xigoi 7mo agoFor me, Markdown produces a lot of unnecessary cognitive load compared to other markup languages. • I have to decide whether to use asterisks or underscores for bold and italic. • I have to decide whether to use asterisks, hyphen-minuses, or plus signs for unordered lists. • I have to remember all the various rules and edge cases about parsing.
- chrisweekly 7mo agoI suggest trying Obsidian for WYSIWYG markdown editing. It beats heck out of typing it raw and eliminates that cognitive load.
- xigoi 7mo agoI don’t like WYSIWYG editing, as it makes the formatting invisible.
- delecti 7mo agoThen you might like Obsidian. When the cursor is in some bit of formatted text, it displays all of the characters. When the cursor is elsewhere, it just shows the formatted text. In the worst case, the barrier to entry and exit are pretty low.
- lolive 7mo agoObsidian has 2 main advantages to me. First you can switch from WYSIWYG to text editor instantly. Then you have an outline where you can manipulate your “markdown blocks” [i.e title and its content] by drag n drop. Or extract a “markdown block” as a new note, and leave a reference where it originally was extracted from. And then [the killing feature], it displays the content of a link, web link or internal link, as a [kind of] iframe, if you prepend a ! to the link.
- nxpnsv 7mo ago1&2 just pick one, it doesn’t matter. 3 mostly you’re the parser… if you’re after accuracy there are better versions, but it sure is simple to read and write
- mh- 7mo ago> compared to other markup languages I think it would be easier for me to appreciate your comment if you named some of these other languages. Markdown is the only standardized one I regularly come across that I type by hand, these days. What are you contrasting to? As for Markdown specifically- the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and (). But that's just because I don't use it enough to have the muscle memory.
- xigoi 7mo ago> I think it would be easier for me to appreciate your comment if you named some of these other languages. HTML? Also my markup language I created for myself, which is currently not published.
- mkldd 7mo ago[flagged]
- nickloewen 7mo agoI used to flip the link syntax all the time too. What finally helped me to remember it was noticing how I write links in plaintext emails. In email, I naturally write things like "...on the example website (www.example.com)..." Markdown keeps those () in the same place, and just adds the [] so you can delimit the visible text: "...on the [example website](www.example.com)..."
- mschnell 7mo agoI remember it like this: If you squint the brackets around the link text make a rectangle and look almost like a button you can press. [Press here](to.go.there)
- klez 7mo ago> the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and () I remember it as passing parameters to a function that requires an URL as an argument. Maybe it's not the most straightforward way, but it works for me
- GandalfHN 7mo ago[flagged]
- GandalfHN 7mo ago[flagged]
- arunbose 7mo ago[dead]
- recursivedoubts 7mo agoI came here to say this.
- nostrademons 7mo agoIt's also worth remembering that markdown tried very hard to encode conventions that were already used in Usenet, email, and other text media. A > to indicate a quote was widespread Usenet convention. Asterisks or underscores to indicate emphasis was also a common convention; both are legal because both were common. Double asterisk or double underscores to indicate really, really emphasizing something was also a common convention. So were asterisks to display a bulleted list, blank lines to separate paragraphs, and indenting 4+ spaces to write code. It's a good example of "pave the path" design philosophy, where you do what users are already doing rather than trying to impose some platonic ideal of what the world should be like. And it works quite well at that.
- reaperducer 7mo agomarkdown tried very hard to encode conventions that were already used in Usenet, email, and other text media For those of you who weren't there: *bold* _underline_ ~strikethrough~ /italics/ > Quotation - list - list - list I've been using these for almost half a century. They're much easier and more intuitive than Markdown. I see no compelling reason to change.
- nostrademons 7mo agoYour quotation and list syntax should work out of the box in most Markdown flavors (HN has a very non-standard and crippled version - basically nothing other than italics, paragraphs, and code/preformatting works.) Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an <em> (emphasis) tag, which is rendered as italics in most browsers.
- 8n4vidtmkvmk 7mo agoWhat ambiguities are there with bold?
- nickloewen 7mo ago
- sph 7mo agoWorse is better doesn’t mean worst is best either.
- AlotOfReading 7mo agoMarkdown is pretty far from the worst. It's decent and unobtrusive. Worst would be something like Troff or jira formatting. Midtier would be RST.
- Joker_vD 7mo agoUgh, troff. It's mind-boggling that the closest way to have an actual (hyper)link in a manpage is to use your pager's "search for text" function. No, "JuSt usE gNu iNfO it'S beTtER" is not an answer either.
- dasyatidprime 7mo agogroff can produce output with links in it, and does by default in HTML mode! The GNU version of the Unix man page macro set has .UR and .UE for “URI start” and “URI end”. (I don't know whether these were present earlier in the lineage or whether they were introduced by GNU.) Also, the lowdown Markdown converter when in man output mode will output those for links. For fun, try: echo 'Hi there! Have a [hyperlink](https://www.gnu.org/software/groff/manual/groff.html).' | lowdown -st man | groff -man -Thtml There's also support for OSC 8 terminal hyperlink sequences throughout most of the groff toolchain: grotty(1) supports outputting them, and less(1) supports passing them through, including ^O^P and ^O^N gestures for moving between them. But man(7) says they're not enabled for grotty output by default. “Options” describes the rationale in its item for “-rU1”: “grohtml enables them by default; grotty does not, pending more widespread pager support for OSC 8 escape sequences.” So if I set MANROFFOPT=-rU1 in the environment, I can get clickable links in man… if the man page author included them that way in the first place. I'm not sure how common that is in the wild, but grepping the ones on my system, I find firejail(1) contains a link to a GitHub issue embedded in that way, and it does indeed work when I hit ^O^N to seek to it and then C-mouse1—though the mouse gesture I have Alacritty using for links doesn't seem to work through tmux (there might be a way involving twiddling the tmux terminal-features setting, but I ran out of steam before trying this), and I didn't see a great way to get either grotty or Alacritty to style them on display instead of having them blend into the surrounding text, so it's still kind of scuffed in practice. (Though I bet the cool kids have moved on from Alacritty by now?) less displays the link target in the status line when you use the navigation commands, so it's not inaccessible, but for opening selected links directly from less with the ^O^O gesture rather than leaning on terminal support, it looks like you need to explicitly set the LESS_OSC8_ANY and/or LESS_OSC8_‹scheme› environment variable to a shell command that outputs a shell command pattern to substitute the link into; if I set LESS_OSC8_ANY='echo xdg-open %o' then it passes it to my Firefox. I wonder if they'd take a patch (or if any existing distributions patch it) to use that as the default? That was a fun little rabbit hole to go down, thank you.
- ZoomZoomZoom 7mo agoThis is exactly why ReStructured Text is better/worse.
- neonstatic 7mo ago> worse is better It's a very old idea In the paper, Copernicus postulated the principle that "bad money drives out good", which later came to be referred to as Gresham's law after a later describer, Sir Thomas Gresham. This phenomenon had been noted earlier by Nicole Oresme, but Copernicus rediscovered it independently. Gresham's law is still known in Poland and Central and Eastern Europe as the Copernicus-Gresham Law. https://en.wikipedia.org/wiki/Monetae_cudendae_ratio https://en.wikipedia.org/wiki/Monetae_cudendae_ratio
- edanm 7mo agoI'm not quite sure I understand the connection.
- neonstatic 7mo agoI see one, but then maybe I am just seeing things. The wikipedia page about "worse is better" re: software linked above states: It refers to the argument that software quality does not necessarily increase with functionality: that there is a point where less functionality ("worse") is a preferable option ("better") in terms of practicality and usability. Copernicus' idea about money has a similar structure - "better" money such as precious metals, art, etc. is being hoarded due to its perceived desirability, leading to more "worse" money in circulation. As a result, the "worse" money is actually "better" at fulfilling its role as currency (bc it's not hoarded). So there is also a point where "worse" becomes "better".
- atanasi 7mo agoBad money drives out good money only if there is a legal tender law such that both have to be accepted for the same nominal value. In this case, good money is hoarded because it cannot be traded for its true value.
- zelphirkalt 7mo agoSaying, that it is the best compromise we know of is going a little far, I think. There are more readable intuitive formats, but they simply don't have the spread, that markdown formats have.
- NetMageSCW 7mo agoWhy do you think that is?
- zelphirkalt 7mo agoBecause I think, that there are other formats, whose formatting rules are more intuitive than Markdown's formatting rules. For example: (1) I can never remember, whether I need to use [] or () first, when embedding an image. In Org mode syntax one simply uses [] for both parts. (2) Or whether ** is bold or italic or * is bold or italic. Other formats use the well known / to mean italic, which optically already makes more sense and also doesn't interfere with something being bold or not, because it is a separate symbol. This makes Markdown also harder to parse btw..
- throw0101c 7mo ago> 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! What about something like AsciiDoc (or reStructuredText)? * https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/ https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar... * "Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code": https://news.ycombinator.com/item?id=33468213 https://news.ycombinator.com/item?id=33468213 Simply things are still simple, but there seem to be more advanced options for those that want/need them.
- Analemma_ 7mo agoThe problem is that proposed Markdown alternatives are targeting a vanishingly small niche of scenarios: for almost all simple writing Markdown is good enough, and for anything too complicated for Markdown, people will use HTML or LaTeX/Typst. The in-betweens just don't seem to have a reason to exist.
- heresie-dabord 7mo ago> barriers to producing documentation--should be minimized. Writing well is difficult enough! Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure. In TFA, the author writes: The Bad -- We don’t know what we want. It's exactly this. We fail to recognise why we write and then we fail to express it. We don't write technical documentation for the equivalent of KLOCs. Writing something useful and meaningful -- not just performative filler for KPIs or SEO enshittification -- requires structure. Anything valuable that can't be retrieved effectively is lost. Imagine losing actual code or database rows at the same rate. We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding. We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe. > Markdown is the best compromise we know of It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem. As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time> It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
- duxup 7mo agoIt's the inescapable truth that even after sitting down and engineering a magical solution ... sometimes just a basic CRUD function with just a couple bits added that doesn't have all the bells and whistles is what actually lasts when I write code and requires less maintenance. There's the stuff that wows people and the stuff that people actually USE.
- hulitu 7mo ago> We want to encourage people to produce written output with minimal friction. What's wrong with .txt ?
- NetMageSCW 7mo agoWe also want standard structure so the more than the content is understood.