9 ms·

It's too bad that AsciiDoc still hasn't really caught on like Markdown. It's a whole lot nicer for more-complicated documents. I understand their reasons for no

It's too bad that AsciiDoc still hasn't really caught on like Markdown. It's a whole lot nicer for more-complicated documents. I understand their reasons for not using it here, but it still seems like a perfect fit for this task. Eclipse still seems to be working on a formal spec, but hopefully that will help implementations to grow and adoption to increase. In any case, avoiding raw HTML is a huge improvement. I like this document. It's well written, and it provides a clear explanation for every major technical decision made on the way.

swyx 4y ago
Markdown is "worse is better". AsciiDoc is more powerful, but has a steeper learning curve, therefore it lost. tale as old as tech. EDIT: i'm compiling a list of "Worse is Better" technology battles: - Mixed paradigm languages vs Functional languages - Typescript vs Flow - React+Redux beat Angular and Elm - VHS beat Betamax - AC beat DC - what else? please share more here https://hashnode.com/preview/636602dec7fec996b85c7165 https://hashnode.com/preview/636602dec7fec996b85c7165 (draft!)
- nerdponx 4y ago
  > has a steeper learning curve Does it? I think Markdown "won" for a variety of reasons (Github? Slack? Pandoc?). I don't think AsciiDoc is so much more complicated than Markdown that people can't learn it quickly. The reason Markdown is now standard is that people like standardized things. They want to use the same syntax in their chatroom, forum, ad-hoc readme filed, and doc comments in code. And if they're already using one markup language, why learn another? Why not use the same one everywhere? It's not that AsciiDoc is complicated in general, it's that it's ever so slightly too rigid for "ad-hoc" markup in places like Discord and Hacker News. Thus people end up learning Markdown because it really is the best fit for those platforms, and then people don't want to learn another markup language, and so you get a snowball effect of implementation support and popularity. And thus we are stuck with Markdown everywhere. This isn't necessarily a bad outcome. But that's how I see it. I still want AsciiDoc to gain more traction in technical writing!
  - smashed 4y ago
    I think you are on the right track but may be over estimating the "average" internet user capabilities? I had to migrate a couple of projects from awful, big ridden, wysiwyg editors to markdown and it's a huge challenge. Many people expect everything to work just as Ms Office/word does. Anything behaving in any way different than their benchmark is wrong.. Now, going from such a mindset to Markdown is a huge endeavour. You need to re-educate your user. Many will never appreciate the raw, code-like nature of markdown and will dread it the entire time they have to endure it.
    - andylynch 4y ago
      I really don’t get the push for markdown etc over WYSIWYG for everyday people. The _very first_ web browser was also an GUI editor, and then you already had proper rich text editors since at least the Macintosh. Why should users not expect something as basic as formatting text to follow UI conventions established through what’s now forty-odd years of use by billions or people? It is akin to asking them not to complain when swapping a steering wheel for something like the tiller on 1880s cars.
      - rjsw 4y ago
        Markdown works better in a VCS than WYSIWYG formats.
      - samus 4y ago
        Technical users are an important user segment as well, especially those used to advanced text editors and IDEs. They don't have the patience to conform to the changing and often poorly thought-through user interfaces of text processors and want the flexibility to use more powerful tools if required. Do it like JIRA: give them both. People used to GUIs can use the WYSIWYG interface, and power users can use Markdown.
        Marta_B 4y ago
        CKEditor also gives that option – where you can type in Markdown if you prefer that over the rich-text UI. So both sides can be happy.
- gherkinnn 4y ago
  - Javascript vs * - English vs * Both awful languages in many ways. And yet, here we are. Also who the fuck wants to speak Esperanto? In some cases I don’t think it’s “worse is better”, much as “the flexible beats the over-designed ivory tower”. Another way of looking at it is “capabilities matter, vulnerabilities don’t”. Think of a river carving its way through a valley. It is terribly undesigned and messy but it flows exactly where it had to.
  - tgv 4y ago
    English isn't a bad language; its spelling is highly inconsistent, but for the rest it's simpler than most other languages. The only advantage Esperanto has is that it doesn't give (much of) an advantage to pre-existing native speakers. For the rest, it's perhaps even harder to learn than English, and --when hypothetically adopted on a large scale-- will develop into regional dialects.
    - iopq 4y ago
      Spanish spelling is better, pronunciation is easier (no th, only 5 vowels, etc.), native speakers almost as numerable, allows you to understand Portuguese, Italian, etc. It wasn't chosen, America just won
      - tgv 4y ago
        Spanish orthography is pretty regular, but then you have 42 inflections per verb for three different patterns, and the most important verbs are of course highly irregular. Not to mention the fact that the difference between ser and estar isn't easy to learn. And there are a few more things that are hard (limiting to pronunciation: the guttural j/g, and the rr; counting syllables is a recurring question in quizzes). > It wasn't chosen, America just won That doesn't make English a bad language. Perhaps America (I guess you're referring to the USA) won because of English is so easy. But cultural, financial and political influence obviously count.
        samus 4y ago
- nix23 4y ago
  >AC beat DC Well that's not true, especially not in a data-center. It's just better for general long-distance energy transfer.
- iamtedd 4y ago
  In what way is DC better than AC? To my knowledge AC rightfully won - much easier to transport over long distances, whereas DC required a generator nearly on every city block (among other reasons).
  - silvestrov 4y ago
    From Wikipedia: > High-voltage direct current (HVDC) is used to transmit large amounts of power over long distances or for interconnections between asynchronous grids. When electrical energy is to be transmitted over very long distances, the power lost in AC transmission becomes appreciable and it is less expensive to use direct current instead of alternating current. For a very long transmission line, these lower losses (and reduced construction cost of a DC line) can offset the additional cost of the required converter stations at each end. https://en.wikipedia.org/wiki/Electric_power_transmission#High-voltage_direct_current https://en.wikipedia.org/wiki/Electric_power_transmission#Hi...
  - pletnes 4y ago
    AC voltage can be changed up/down cheaply by making a couple of (relatively) simple wire coils. Also AC engines are simple, compact and reliable. Recall that the choice of AC was also taken over 100 years ago, before any electronics were around.
  - mananaysiempre 4y ago
    AC is easy to change the voltage of with 20th-century tech (even high-power 21st-century tech for DC amounts to “convert to AC, shift that, filter it back” with some—crucial—improvements), so it works reasonably well over moderate distances at moderate power if you shift down as late as possible, but it’s absolutely awful for transporting large quantities of energy over long distances, because of the skin effect. Essentially, thick round wires are useless for AC because the current gets expelled to a thin layer on the surface (determined by the frequency and the properties of the material, roughly independent of how much you were trying to cram in there), thus the resistance goes down as the radius rather than the cross-sectional area, and you end up using absolutely asinine amounts of (nowadays very expensive) copper or (kind of expensive) aluminium in high-voltage lines. (Using flat buses instead of wires does work, but then sharp edges mean you get a lot more current leaking into the air.) If you don’t have high-power semiconductor components you can use to convert to AC and back in order to shift voltages or to just convert to AC in order to power industrial motors, you will have to grit your teeth and bear it—it seems that mechanical motor-generators are simply too unreliable. But for the last twenty or so years we’ve had them, and I understand that people are once again looking seriously at high-voltage DC. Of course, grids are huge and expensive, so it may be some time until implementations become common. I don’t think any of this counts as an instance of worse is better, though,—it’s just that the ease of building alternators changed dramatically over the last few decades.
- xdfgh1112 4y ago
  PHP
- Lvl999Noob 4y ago
  Isn't typescript better than flow? In what ways is flow better?
  - 0xfffafaCrash 4y ago
    Yeah, TS isn’t just better than Flow. It’s vastly better in almost any way one can think of. One of the few cases where the answer isn’t even “it depends.” I have to imagine swyx is either trolling here or has some very special contrarian opinion to almost anyone who has used these two technologies.
  - xwx 4y ago
    The main advantage Flow has over Typescript is soundness. Neither language is sound, but Flow tries a bit harder, and so there are fewer cases where you write bugs that 'should' be caught by the type checker. Here are a few examples of unsoundness in TS: https://www.typescriptlang.org/play?strictFunctionTypes=false#example/soundness https://www.typescriptlang.org/play?strictFunctionTypes=fals... https://flow.org/en/docs/lang/types-and-expressions/#toc-soundness-and-completeness https://flow.org/en/docs/lang/types-and-expressions/#toc-sou...
  - sequoia 4y ago
    Flow is not better than typescript. People who say it’s “better”, what they mean is it’s more strict, which really means more rigid. The rigidity is a complete pain in the ass that’s not well suited to web UI development and leads to all kinds of convolution. To take one example: I use a Graphql to flow type generator for query fragment. That tool generates inexact types. So I’ll end up with an array of values of this type from a Graphql query, data objects with 10 keys for example. Then I want to pass this to a charting library, but I need to add a “color” property to each data object for the charting library. This is not possible with flow. My options are: - create a new type with color property and spread the existing type: this is not possible because the existing type is inexact and I have no way to convince flow it doesn’t already have a color property - just add a color property: this won’t work because I get a flow error later when I try to read the property, plus I don’t get the type check I’d like - create a new type plucking every other field from the existing type 1x1, then create a mapping function moving every property to the new type 1x1 - use $FlowFixMe to disable type checking altogether The only options that work are the last two, and they either break typing altogether or require dozens of additional lines of code that serve no purpose but satisfying Flow. And or course you need a comment to explain why the hell you’re mapping properties over one by one. I don’t need a type system that’s this “correct.” I’m not writing mathematical proofs, I’m writing web UIs, and this level of rigidity just gets in the way and leads to weird, overly verbose code.
- juliendorra 4y ago
  Love the idea of the list, the intro sets the context very nicely! Some suggestions: - HTML is a worse hypertext system (no typed links, no transclusion, no native index or versioning) and beat all the previous professional but centralized hypertext systems in just 3 years. It’s worse than HyperCard on the symmetrical authoring and viewing side, too. - json, from an historical perspective is really a worse xml (xml can serialize a much wider range of data structures and relationships, including circular ones, can be validated by schemas, etc.). But simpler to read, write and reason about. It limits ended up biting devs and it was extended in various, non standards ways
  - swyx 4y ago
    thanks for the contributions!
- gryn 4y ago
  angular ? really ??? in what way is it better ? I've used vue, angular, and react in different projects and honestly I'd take react with hooks every single time If I had the choice.
- NoboruWataya 4y ago
  > AsciiDoc is more powerful, but has a steeper learning curve How does this make it better? Sounds like it makes it worse. Maybe a better summation is "less is more".
  - remram 4y ago
    GP seems to be using a definition of "better" that doesn't include difficulty. I agree that it's a bad decision when evaluating a markup language used in so many contexts as Markdown.
    - swyx 4y ago
      literally just referencing richard gabriel’s use of the word thats all. each side has genuine champions but usually one side is more purist (however defined) than the other and they lose 80% of the time
- talkingtab 4y ago
  "Worse is better" is always true if you choose the criteria carefully. For example it is always worse to eat food because it might be poisonous. Markdown certainly has limitations, but it more people know it and people can and do use it. More "powerful" is a good criteria, unless you have to pay the price. I applaud the decision and the work by the authors. It worked.
- photochemsyn 4y ago
  As far as MDN Web Docs, what about variable declaration, i.e. deprecating the JS var in favor of let and const, universally? var has some weird behavior (hoisting) and it seems (no expert here) that only using let and const in code has many benefits. Is it historical inertia, backwards compatibility, preference?
  - wbamberg 4y ago
    I'm not sure exactly what you're asking about, but if it's our use of `var` in code examples, we had a big project this summer to eradicate `var` in favour of `const` and `let`. This started out as a project for the Writing Day at the Write the Docs Portland conference (https://openwebdocs.org/content/posts/writing-day-wtd-portland-2022/ https://openwebdocs.org/content/posts/writing-day-wtd-portla...). It then continued as a much bigger thing: https://openwebdocs.org/content/posts/2022-q3-report/#modernization-code-samples-on-mdn https://openwebdocs.org/content/posts/2022-q3-report/#modern.... Much of the work was done by volunteers, and it's a great example of the kind of project that I don't think would have been possible back when MDN content was in a Wiki. If you're asking about whether we should un-recommend `var` more strongly: looking at the page for `var` (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...) - well, maybe you are right...
- appleflaxen 4y ago
  I thought Linux vs BSD and C vs Lisp were traditional examples of this.
  - mdaniel 4y ago
    > C vs Lisp I wish there was a statically typed functional language on the right hand side, because `(defun take-action (thing) (format "ohgawd what type is thing?!"))` is for sure less powerful than `int take_action(struct foo *thing);`
  - sicp-enjoyer 4y ago
    Also C vs pascal and ada.
- radarsat1 4y ago
  what was the deal with Betamax though? was VHS actually easier or have any advantages, or did it just win due to marketing? (honest curiosity here, i don't know the technicalities)
  - urban_alien 4y ago
    The porn industry adopted VHS and managed to make it the standard, basically
    - sli 4y ago
      This is a myth. Porn was available on Beta and far more non-porn VHS tapes were being sold than porn. Porn only made up a small fraction of VHS sales. Even the idea that Beta was strictly better than VHS is mostly modern myth.
  - Karunamon 4y ago
    One benefit I heard called out was that early Betamax capped the tape capacity to one hour, which meant you couldn't record things like full sports games and quite a few movies. Sony didn't change this until VHS came along with its slower tape speeds and more recording time, and by then it was too late. Also, VHS was cheaper, and while Betamax was technically inferior, it wasn't inferior in a way that the average buyer would notice.
    - radarsat1 4y ago
      interesting thanks!
- developerDan 4y ago
  HDMI beat DP, it’s one that will always bug me.
  - swyx 4y ago
    good suggestion ! why does it bug you?
- bee_rider 4y ago
  - Markdown vs LaTeX - HTML vs LaTeX (ok maybe I'm being a bit silly)
kubanczyk 4y ago
Out of curiosity I've looked up "asciidoc tutorial". 10% into the first page and I see this: A [.myrole]#custom role# must be fulfilled by the theme. Wait, is this in example 7 of 97? That's already... disturbing? But I scroll just a little down and I see examples 11 and 12: https://chat.asciidoc.org[Discuss AsciiDoc,role=external,window=_blank] CAUTION If the link text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes. link:++https://example.org/?q=[a b]++[URL with special characters] Isn't this literally worse than HTML?
- keybored 4y ago
  Having to use quotes (or any other symbol) sometimes based on learned rules is a big no-no for lightweight markup in my book.
  - xigoi 4y ago
    In Markdown, you sometimes have to put a backslash before special characters.
    - keybored 4y ago
      I was talking about quoting or grouping things. Either require things like quotes for certain constructs all the time (no matter the content) or don’t.
    - keybored 4y ago
      > In Markdown, you sometimes have to put a backslash before special characters. I think I get it now. Yes, I agree that sometimes-rules for escaping is bad. Should have to require escaping metacharacters all the time, not just in certain contexts.
- nerdponx 4y ago
  What tutorial? The official docs are well-written and rightly don't show advanced features at the beginning: https://docs.asciidoctor.org/asciidoc/latest/document-structure/ https://docs.asciidoctor.org/asciidoc/latest/document-struct... > Isn't this literally worse than HTML? Not in my opinion. How often does this actually come up in technical writing? I'm happy with one or two ugly edge cases if it means that the overall experience is nice: that's a perfectly fine tradeoff to me.
enriquto 4y ago
> In any case, avoiding raw HTML is a huge improvement. Why is that? Raw HTML is quite simple to understand and edit. Especially modern html5. There may be a slightly marginal improvement with bold markings with stars versus b tags, but I wouldn't call it "huge" by any means. EDIT: of course, you can build nightmares with plain HTML. Especially when it is auto-generated. But hand-written simple HTML is essentially equivalent to markdown, and I'd say that it is even simpler for some things (e.g., links, anchors and tables).
- Lvl999Noob 4y ago
  One example was given in the article itself. Raw HTML requires escaping html tags. This leads to completely inlegible code that would be impossible for someone to review without rendering the page and checking the output.
  - enriquto 4y ago
    The xmp tag would be the natural answer to this problem. It still works in browsers, but unfortunately it became deprecated on the html5 standard. A hackish (thus beautiful!) answer is to use textarea tags, suitably styled.
- hiAndrewQuinn 4y ago
  Reading HTML with your eyes includes far more line noise than reading Markdown, though.
mumumu 4y ago
Linux considered AsciiDoc. But went with ReStructuredText. So, I'd look into that instead. I'd guess Mozilla chosen a format most people are familiar with.
Grokify 4y ago
AsciiDoc may have a naming issue. I'm speculating that it's not restricted to the ASCII character set but the immediate question that comes to mind is what is restricted to ASCII and if it can support Unicode or even ISO 8859.
- michaelcampbell 4y ago
  Anecdata to be sure, but over the years I've seen a lot of Asciidoc vs Markdown articles, and naming has never once been listed as an issue.
thiht 4y ago
I used AsciiDoc for a while at my first job because it looked better than Markdown on paper, but I hated it. The syntax made no sense to me, and AsciiDoctor (the de facto tool to generate formatted AsciiDoc documents at the time, not sure if it has changed) was a pain in the ass to use and the output was basically impossible to configure (I just wanted to use the colors of my company). Markdown feels a lot of less powerful, but somehow "just works". So now I just stick with Markdown everywhere and have never regretted it so far.
- nerdponx 4y ago
  Yep, AsciiDoc implementations/tooling are a big part of why I think it has been slow to catch on. I think a standardized specification will go a long way towards addressing that. At least then implementations can target the specifications, or at least target some well-defined subset of it, and we won't be stuck with one or two monolithic legacy applications. To be clear, I don't see AsciiDoc as a Markdown replacement. But part of what I like about it is that it's simple enough to be used in most contexts where Markdown is currently used. I wrote my masters thesis with Markdown, Pandoc, and GPP, using Pandoc to generate a PDF via TeX. If I could use the same workflow but with AsciiDoc instead of Markdown, I would.

swyx 4y ago

Markdown is "worse is better". AsciiDoc is more powerful, but has a steeper learning curve, therefore it lost. tale as old as tech. EDIT: i'm compiling a list of "Worse is Better" technology battles: - Mixed paradigm languages vs Functional languages - Typescript vs Flow - React+Redux beat Angular and Elm - VHS beat Betamax - AC beat DC - what else? please share more here https://hashnode.com/preview/636602dec7fec996b85c7165 https://hashnode.com/preview/636602dec7fec996b85c7165 (draft!)

nerdponx 4y ago
> has a steeper learning curve Does it? I think Markdown "won" for a variety of reasons (Github? Slack? Pandoc?). I don't think AsciiDoc is so much more complicated than Markdown that people can't learn it quickly. The reason Markdown is now standard is that people like standardized things. They want to use the same syntax in their chatroom, forum, ad-hoc readme filed, and doc comments in code. And if they're already using one markup language, why learn another? Why not use the same one everywhere? It's not that AsciiDoc is complicated in general, it's that it's ever so slightly too rigid for "ad-hoc" markup in places like Discord and Hacker News. Thus people end up learning Markdown because it really is the best fit for those platforms, and then people don't want to learn another markup language, and so you get a snowball effect of implementation support and popularity. And thus we are stuck with Markdown everywhere. This isn't necessarily a bad outcome. But that's how I see it. I still want AsciiDoc to gain more traction in technical writing!
- smashed 4y ago
  I think you are on the right track but may be over estimating the "average" internet user capabilities? I had to migrate a couple of projects from awful, big ridden, wysiwyg editors to markdown and it's a huge challenge. Many people expect everything to work just as Ms Office/word does. Anything behaving in any way different than their benchmark is wrong.. Now, going from such a mindset to Markdown is a huge endeavour. You need to re-educate your user. Many will never appreciate the raw, code-like nature of markdown and will dread it the entire time they have to endure it.
  - andylynch 4y ago
    I really don’t get the push for markdown etc over WYSIWYG for everyday people. The _very first_ web browser was also an GUI editor, and then you already had proper rich text editors since at least the Macintosh. Why should users not expect something as basic as formatting text to follow UI conventions established through what’s now forty-odd years of use by billions or people? It is akin to asking them not to complain when swapping a steering wheel for something like the tiller on 1880s cars.
    - rjsw 4y ago
      Markdown works better in a VCS than WYSIWYG formats.
    - samus 4y ago
      Technical users are an important user segment as well, especially those used to advanced text editors and IDEs. They don't have the patience to conform to the changing and often poorly thought-through user interfaces of text processors and want the flexibility to use more powerful tools if required. Do it like JIRA: give them both. People used to GUIs can use the WYSIWYG interface, and power users can use Markdown.
      - Marta_B 4y ago
        CKEditor also gives that option – where you can type in Markdown if you prefer that over the rich-text UI. So both sides can be happy.
gherkinnn 4y ago
- Javascript vs * - English vs * Both awful languages in many ways. And yet, here we are. Also who the fuck wants to speak Esperanto? In some cases I don’t think it’s “worse is better”, much as “the flexible beats the over-designed ivory tower”. Another way of looking at it is “capabilities matter, vulnerabilities don’t”. Think of a river carving its way through a valley. It is terribly undesigned and messy but it flows exactly where it had to.
- tgv 4y ago
  English isn't a bad language; its spelling is highly inconsistent, but for the rest it's simpler than most other languages. The only advantage Esperanto has is that it doesn't give (much of) an advantage to pre-existing native speakers. For the rest, it's perhaps even harder to learn than English, and --when hypothetically adopted on a large scale-- will develop into regional dialects.
  - iopq 4y ago
    Spanish spelling is better, pronunciation is easier (no th, only 5 vowels, etc.), native speakers almost as numerable, allows you to understand Portuguese, Italian, etc. It wasn't chosen, America just won
    - tgv 4y ago
      Spanish orthography is pretty regular, but then you have 42 inflections per verb for three different patterns, and the most important verbs are of course highly irregular. Not to mention the fact that the difference between ser and estar isn't easy to learn. And there are a few more things that are hard (limiting to pronunciation: the guttural j/g, and the rr; counting syllables is a recurring question in quizzes). > It wasn't chosen, America just won That doesn't make English a bad language. Perhaps America (I guess you're referring to the USA) won because of English is so easy. But cultural, financial and political influence obviously count.
      - samus 4y ago
nix23 4y ago
>AC beat DC Well that's not true, especially not in a data-center. It's just better for general long-distance energy transfer.
iamtedd 4y ago
In what way is DC better than AC? To my knowledge AC rightfully won - much easier to transport over long distances, whereas DC required a generator nearly on every city block (among other reasons).
- silvestrov 4y ago
  From Wikipedia: > High-voltage direct current (HVDC) is used to transmit large amounts of power over long distances or for interconnections between asynchronous grids. When electrical energy is to be transmitted over very long distances, the power lost in AC transmission becomes appreciable and it is less expensive to use direct current instead of alternating current. For a very long transmission line, these lower losses (and reduced construction cost of a DC line) can offset the additional cost of the required converter stations at each end. https://en.wikipedia.org/wiki/Electric_power_transmission#High-voltage_direct_current https://en.wikipedia.org/wiki/Electric_power_transmission#Hi...
- pletnes 4y ago
  AC voltage can be changed up/down cheaply by making a couple of (relatively) simple wire coils. Also AC engines are simple, compact and reliable. Recall that the choice of AC was also taken over 100 years ago, before any electronics were around.
- mananaysiempre 4y ago
  AC is easy to change the voltage of with 20th-century tech (even high-power 21st-century tech for DC amounts to “convert to AC, shift that, filter it back” with some—crucial—improvements), so it works reasonably well over moderate distances at moderate power if you shift down as late as possible, but it’s absolutely awful for transporting large quantities of energy over long distances, because of the skin effect. Essentially, thick round wires are useless for AC because the current gets expelled to a thin layer on the surface (determined by the frequency and the properties of the material, roughly independent of how much you were trying to cram in there), thus the resistance goes down as the radius rather than the cross-sectional area, and you end up using absolutely asinine amounts of (nowadays very expensive) copper or (kind of expensive) aluminium in high-voltage lines. (Using flat buses instead of wires does work, but then sharp edges mean you get a lot more current leaking into the air.) If you don’t have high-power semiconductor components you can use to convert to AC and back in order to shift voltages or to just convert to AC in order to power industrial motors, you will have to grit your teeth and bear it—it seems that mechanical motor-generators are simply too unreliable. But for the last twenty or so years we’ve had them, and I understand that people are once again looking seriously at high-voltage DC. Of course, grids are huge and expensive, so it may be some time until implementations become common. I don’t think any of this counts as an instance of worse is better, though,—it’s just that the ease of building alternators changed dramatically over the last few decades.
xdfgh1112 4y ago
PHP
Lvl999Noob 4y ago
Isn't typescript better than flow? In what ways is flow better?
- 0xfffafaCrash 4y ago
  Yeah, TS isn’t just better than Flow. It’s vastly better in almost any way one can think of. One of the few cases where the answer isn’t even “it depends.” I have to imagine swyx is either trolling here or has some very special contrarian opinion to almost anyone who has used these two technologies.
- xwx 4y ago
  The main advantage Flow has over Typescript is soundness. Neither language is sound, but Flow tries a bit harder, and so there are fewer cases where you write bugs that 'should' be caught by the type checker. Here are a few examples of unsoundness in TS: https://www.typescriptlang.org/play?strictFunctionTypes=false#example/soundness https://www.typescriptlang.org/play?strictFunctionTypes=fals... https://flow.org/en/docs/lang/types-and-expressions/#toc-soundness-and-completeness https://flow.org/en/docs/lang/types-and-expressions/#toc-sou...
- sequoia 4y ago
  Flow is not better than typescript. People who say it’s “better”, what they mean is it’s more strict, which really means more rigid. The rigidity is a complete pain in the ass that’s not well suited to web UI development and leads to all kinds of convolution. To take one example: I use a Graphql to flow type generator for query fragment. That tool generates inexact types. So I’ll end up with an array of values of this type from a Graphql query, data objects with 10 keys for example. Then I want to pass this to a charting library, but I need to add a “color” property to each data object for the charting library. This is not possible with flow. My options are: - create a new type with color property and spread the existing type: this is not possible because the existing type is inexact and I have no way to convince flow it doesn’t already have a color property - just add a color property: this won’t work because I get a flow error later when I try to read the property, plus I don’t get the type check I’d like - create a new type plucking every other field from the existing type 1x1, then create a mapping function moving every property to the new type 1x1 - use $FlowFixMe to disable type checking altogether The only options that work are the last two, and they either break typing altogether or require dozens of additional lines of code that serve no purpose but satisfying Flow. And or course you need a comment to explain why the hell you’re mapping properties over one by one. I don’t need a type system that’s this “correct.” I’m not writing mathematical proofs, I’m writing web UIs, and this level of rigidity just gets in the way and leads to weird, overly verbose code.
juliendorra 4y ago
Love the idea of the list, the intro sets the context very nicely! Some suggestions: - HTML is a worse hypertext system (no typed links, no transclusion, no native index or versioning) and beat all the previous professional but centralized hypertext systems in just 3 years. It’s worse than HyperCard on the symmetrical authoring and viewing side, too. - json, from an historical perspective is really a worse xml (xml can serialize a much wider range of data structures and relationships, including circular ones, can be validated by schemas, etc.). But simpler to read, write and reason about. It limits ended up biting devs and it was extended in various, non standards ways
- swyx 4y ago
  thanks for the contributions!
gryn 4y ago
angular ? really ??? in what way is it better ? I've used vue, angular, and react in different projects and honestly I'd take react with hooks every single time If I had the choice.
NoboruWataya 4y ago
> AsciiDoc is more powerful, but has a steeper learning curve How does this make it better? Sounds like it makes it worse. Maybe a better summation is "less is more".
- remram 4y ago
  GP seems to be using a definition of "better" that doesn't include difficulty. I agree that it's a bad decision when evaluating a markup language used in so many contexts as Markdown.
  - swyx 4y ago
    literally just referencing richard gabriel’s use of the word thats all. each side has genuine champions but usually one side is more purist (however defined) than the other and they lose 80% of the time
talkingtab 4y ago
"Worse is better" is always true if you choose the criteria carefully. For example it is always worse to eat food because it might be poisonous. Markdown certainly has limitations, but it more people know it and people can and do use it. More "powerful" is a good criteria, unless you have to pay the price. I applaud the decision and the work by the authors. It worked.
photochemsyn 4y ago
As far as MDN Web Docs, what about variable declaration, i.e. deprecating the JS var in favor of let and const, universally? var has some weird behavior (hoisting) and it seems (no expert here) that only using let and const in code has many benefits. Is it historical inertia, backwards compatibility, preference?
- wbamberg 4y ago
  I'm not sure exactly what you're asking about, but if it's our use of `var` in code examples, we had a big project this summer to eradicate `var` in favour of `const` and `let`. This started out as a project for the Writing Day at the Write the Docs Portland conference (https://openwebdocs.org/content/posts/writing-day-wtd-portland-2022/ https://openwebdocs.org/content/posts/writing-day-wtd-portla...). It then continued as a much bigger thing: https://openwebdocs.org/content/posts/2022-q3-report/#modernization-code-samples-on-mdn https://openwebdocs.org/content/posts/2022-q3-report/#modern.... Much of the work was done by volunteers, and it's a great example of the kind of project that I don't think would have been possible back when MDN content was in a Wiki. If you're asking about whether we should un-recommend `var` more strongly: looking at the page for `var` (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...) - well, maybe you are right...
appleflaxen 4y ago
I thought Linux vs BSD and C vs Lisp were traditional examples of this.
- mdaniel 4y ago
  > C vs Lisp I wish there was a statically typed functional language on the right hand side, because `(defun take-action (thing) (format "ohgawd what type is thing?!"))` is for sure less powerful than `int take_action(struct foo *thing);`
- sicp-enjoyer 4y ago
  Also C vs pascal and ada.
radarsat1 4y ago
what was the deal with Betamax though? was VHS actually easier or have any advantages, or did it just win due to marketing? (honest curiosity here, i don't know the technicalities)
- urban_alien 4y ago
  The porn industry adopted VHS and managed to make it the standard, basically
  - sli 4y ago
    This is a myth. Porn was available on Beta and far more non-porn VHS tapes were being sold than porn. Porn only made up a small fraction of VHS sales. Even the idea that Beta was strictly better than VHS is mostly modern myth.
- Karunamon 4y ago
  One benefit I heard called out was that early Betamax capped the tape capacity to one hour, which meant you couldn't record things like full sports games and quite a few movies. Sony didn't change this until VHS came along with its slower tape speeds and more recording time, and by then it was too late. Also, VHS was cheaper, and while Betamax was technically inferior, it wasn't inferior in a way that the average buyer would notice.
  - radarsat1 4y ago
    interesting thanks!
developerDan 4y ago
HDMI beat DP, it’s one that will always bug me.
- swyx 4y ago
  good suggestion ! why does it bug you?
bee_rider 4y ago
- Markdown vs LaTeX - HTML vs LaTeX (ok maybe I'm being a bit silly)

kubanczyk 4y ago

Out of curiosity I've looked up "asciidoc tutorial". 10% into the first page and I see this: A [.myrole]#custom role# must be fulfilled by the theme. Wait, is this in example 7 of 97? That's already... disturbing? But I scroll just a little down and I see examples 11 and 12: https://chat.asciidoc.org[Discuss AsciiDoc,role=external,window=_blank] CAUTION If the link text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes. link:++https://example.org/?q=[a b]++[URL with special characters] Isn't this literally worse than HTML?

keybored 4y ago
Having to use quotes (or any other symbol) sometimes based on learned rules is a big no-no for lightweight markup in my book.
- xigoi 4y ago
  In Markdown, you sometimes have to put a backslash before special characters.
  - keybored 4y ago
    I was talking about quoting or grouping things. Either require things like quotes for certain constructs all the time (no matter the content) or don’t.
  - keybored 4y ago
    > In Markdown, you sometimes have to put a backslash before special characters. I think I get it now. Yes, I agree that sometimes-rules for escaping is bad. Should have to require escaping metacharacters all the time, not just in certain contexts.
nerdponx 4y ago
What tutorial? The official docs are well-written and rightly don't show advanced features at the beginning: https://docs.asciidoctor.org/asciidoc/latest/document-structure/ https://docs.asciidoctor.org/asciidoc/latest/document-struct... > Isn't this literally worse than HTML? Not in my opinion. How often does this actually come up in technical writing? I'm happy with one or two ugly edge cases if it means that the overall experience is nice: that's a perfectly fine tradeoff to me.

enriquto 4y ago

> In any case, avoiding raw HTML is a huge improvement. Why is that? Raw HTML is quite simple to understand and edit. Especially modern html5. There may be a slightly marginal improvement with bold markings with stars versus b tags, but I wouldn't call it "huge" by any means. EDIT: of course, you can build nightmares with plain HTML. Especially when it is auto-generated. But hand-written simple HTML is essentially equivalent to markdown, and I'd say that it is even simpler for some things (e.g., links, anchors and tables).

Lvl999Noob 4y ago
One example was given in the article itself. Raw HTML requires escaping html tags. This leads to completely inlegible code that would be impossible for someone to review without rendering the page and checking the output.
- enriquto 4y ago
  The xmp tag would be the natural answer to this problem. It still works in browsers, but unfortunately it became deprecated on the html5 standard. A hackish (thus beautiful!) answer is to use textarea tags, suitably styled.
hiAndrewQuinn 4y ago
Reading HTML with your eyes includes far more line noise than reading Markdown, though.

mumumu 4y ago

Linux considered AsciiDoc. But went with ReStructuredText. So, I'd look into that instead. I'd guess Mozilla chosen a format most people are familiar with.

Grokify 4y ago

AsciiDoc may have a naming issue. I'm speculating that it's not restricted to the ASCII character set but the immediate question that comes to mind is what is restricted to ASCII and if it can support Unicode or even ISO 8859.

michaelcampbell 4y ago
Anecdata to be sure, but over the years I've seen a lot of Asciidoc vs Markdown articles, and naming has never once been listed as an issue.

thiht 4y ago

I used AsciiDoc for a while at my first job because it looked better than Markdown on paper, but I hated it. The syntax made no sense to me, and AsciiDoctor (the de facto tool to generate formatted AsciiDoc documents at the time, not sure if it has changed) was a pain in the ass to use and the output was basically impossible to configure (I just wanted to use the colors of my company). Markdown feels a lot of less powerful, but somehow "just works". So now I just stick with Markdown everywhere and have never regretted it so far.

nerdponx 4y ago
Yep, AsciiDoc implementations/tooling are a big part of why I think it has been slow to catch on. I think a standardized specification will go a long way towards addressing that. At least then implementations can target the specifications, or at least target some well-defined subset of it, and we won't be stuck with one or two monolithic legacy applications. To be clear, I don't see AsciiDoc as a Markdown replacement. But part of what I like about it is that it's simple enough to be used in most contexts where Markdown is currently used. I wrote my masters thesis with Markdown, Pandoc, and GPP, using Pandoc to generate a PDF via TeX. If I could use the same workflow but with AsciiDoc instead of Markdown, I would.