MDN converted to Markdown
openwebdocs.org
openwebdocs.org
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.
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 (draft!)
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!
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.
Do it like JIRA: give them both. People used to GUIs can use the WYSIWYG interface, and power users can use Markdown.
Can you think of anything less standardized than Markdown?
No, I don’t have to have the correct, best answer to get this.
I just thought it's a neat trick you can apply italics by underscore and make text stand out with back ticks around.
Even least technical people using bold/italics/indent on WhatsApp are using markdown in a way.
At its core, Markdown was little more than a perl script that converted a human readable doc written using many online conventions into HTML.
Others realized this was a brilliant idea and created their own supersets and/or alternatives of markdown. That’s why there’s so many flavors of markdown with little tweaks.
And that’s why Markdown is popular. Because it took advantage of convention built out of years of trial and error.
- 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.
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.
It wasn't chosen, America just won
> 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.
Oh and add to the insanity that we’ll borrow the same French word twice, frozen in each time.
It’s fascinating to see the language evolve through eg India. It’s a secondary language that fills a gap to provide a commonly understood language in a region with massive linguistic diversity. But then it’s developed it’s own regionalisms that are bleeding back into regions where it is the primary language.
It’s kind of like shell scripting to me. It started simple, got random useful things tacked on over time. You can’t formally define it, but it’s pragmatically powerful. And there aren’t real rules despite people trying so hard over the years, just conventions that shift and change. And often the “rule makers” just make things more complicated in the end with only some of it sticking.
I highly recommend the English History Podcast for anyone interested.
https://en.wikipedia.org/wiki/Euro_English#Vocabulary
Anyway as an American I'm always in favor of just giving our language away to anyone to do whatever they want with it, really just go nuts, especially -- throw some z's in there, they really add some pizzazz to the language. (Just ignore the British, they will try to get you to change them back to s's... but you can see what that does to the pizzazz!).
And as an American I reject the British pronunciation of “herb” and “lieutenant.”
There’s nothing unique about English in this regard.
Most languages were pretty calcified by Old or Middle English, and English doesn’t seem to be letting up. But no language is static.
But with tech and mass communication, English is squeezing into many languages.
Pinyin is kind of weird. It’s not borrowing concepts, but lending itself to translation in and out. Based off prior western attempts and observation of Japanese success. Typesetting is more practical, and then computers really push it… the latter I feel awkward about. 1/2 is the typesetting benefit, 1/2 is eurocentrism. I dunno. Maybe I’m overthinking.
The vocabulary is more interesting to me because it’s importing ideas or nuances around ideas. It’s primarily nouns, though.
Learning other languages is great to see the world differently. Even in just French, which is fairly close: eg faire doesn’t have a real English equivalent, but makes total sense. It’s like how I learn programming languages I’ll never use for work, just to see things from their perspective.
I don’t know enough about Asian languages. Working on fleshing out my history knowledge now from Asian perspectives vs what I got in school. Maybe one day I’ll be brave enough to address a language.
Meanwhile compare it to English tense grammar like I did run, I do run, I will run.
I don’t think technical language comparisons are all that enlightening about which one is “best”.
English has a large amount of tenses as well, and if I were you I wouldn't discount the English subjunctive either
Subjunctive may be interesting to analyze, but it's not an additional form of the word.
By my count, English has 12 tenses. You cannot just invent new ones, because people won't be able to understand you. They are fairly regular: present, past, and future, which can be modified by making them perfect, continuous, or both.
"If I had continued boxing professionally, I would have been running 50 km a week" Here's it's a conditional, I think I stuck an extra had in there by accident.
By my English textbook there's 16 tenses, 4x4
Past, present, future, future-in-the-past (would) x Simple, continuous, perfect, continuous-perfect (have been V-ing)
Point being, English grammar is far from simple, as this conversation clearly demonstrated
By next month, I will have run 50km. This means that "I run 50km" completes first, and then next month arrives afterwards.
> By my English textbook there's 16 tenses, 4x4
Depends on how you count tenses. Different textbooks will give different counts, depending on what is considered a "tense". Which is not a reflection of the complexity of English, but a reflection of how hard it is to come up with definitions for terms in linguistics. "Would" is often not counted as a tense, but it may be counted as a tense, particularly if you are explaining English to speakers of a language which have a tense expressing something similar.
> Point being, English grammar is far from simple, as this conversation clearly demonstrated
Most languages are far from simple, I don't think English deserves special attention.
The subjunctive in English is a bit of joke in comparison to the Spanish one.
But this relatively simple grammar is English's strength. Consider how you translate your examples into other languages, especially the future hypotheticals that aren't a trivial concept to communicate period yet the rules for producing them are still simple in English.
In English it's probably distinguishing between a number of vowels like BAD/BED or PULL/POOL, and words like STRENGTH that really test the limits of Mandarin speakers
The grammar is simpler (no gender and fewer inflections), but it has more phonemes than most other Indo-European languages, and has one of the largest vocabularies.
English is not a pidgin language because the grammar is very clearly identifiable as a Germanic language (albeit a clearly simplified form), but with substantial lexical borrowings from other languages. Grammatical simplification and lexical borrowing is not particularly unusual in language development--in fact, English may not even be the biggest offender in these departments (I believe Turkic languages borrowed more from Mongolian languages than English has from Romance languages).
Probably, I would say, the big reason for the lack of Celtic borrowings into English is the fact that, to whatever degree there was admixture between Celtic and Anglo-Saxon populations, English would have been the prestige language, and the prestige language tends to be little affected by borrowings compared to the non-prestige language. You see this with French borrowings: French was the prestige language of England for about 400 years or so, so English starts borrowing all sorts of things from French, but not vice versa. The existence of the Danelaw region--a part of England that was primarily Danish rather than English even when largely ruled by the English--provided a substantial contact region for Old English/Old Norse borrowing, which was helped by the very similar nature of the two languages.
The linguistic evidence has always suggested complete replacement. Even with the prestige language of invaders taking over you would expect some geographical names, especially for small, insignificant and / or out of the way features to persist and yet in England there is pretty much not a single place name that has Celtic origins (outside of Cornwall of course)
Well that's not true, especially not in a data-center. It's just better for general long-distance energy transfer.
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).
> 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#Hi...
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.
I assume there's some reason big hollow wires don't work.
So pipes then. The internet really would have been a series of tubes. ;-)
Wall outlet switchers are also the same. The incoming 120V AC is rectified and smoothed to 170V DC (240V AC goes to ~335V DC) before being chopped up back to AC to lower the voltage. After, it’s rectified and smoothed to the desired voltage. The USB outlet does that to 5V, your phone takes that down to 3.7V, then takes that battery voltage down even lower (1V or whatever)
Basically, AC is used everywhere DC is. People just don’t realize it. Everything runs on DC, but requires AC to change voltages.
This matters for underwater lines especially.
The lower danger of transmission lines is less important once you're committed to stepping voltages up and down, because HVDC transmission lines can still kill you, and there's no real reason we couldn't be using 48VAC inside our houses instead of 120VAC or 240VAC, which would be a lot safer. Historically, though, AC came as a package with transformers and higher-voltage transmission/distribution to substations, and without such super low voltages in houses.
You're exaggerating the technical advantage of AC by a couple of orders of magnitude; you can reasonably transmit 100VDC power about a kilometer, and Edison did, so it's a generator on every 314 city blocks or so.
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.
Here are a few examples of unsoundness in TS: https://www.typescriptlang.org/play?strictFunctionTypes=fals...
https://flow.org/en/docs/lang/types-and-expressions/#toc-sou...
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.
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.
How does this make it better? Sounds like it makes it worse.
Maybe a better summation is "less is more".
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.
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-portla...). It then continued as a much bigger thing: 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/Refe...) - well, maybe you are right...
Linux vs BSD
and
C vs Lisp
were traditional examples of this.
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);`
Also, VHS was cheaper, and while Betamax was technically inferior, it wasn't inferior in a way that the average buyer would notice.
- HTML vs LaTeX (ok maybe I'm being a bit silly)
10% into the first page and I see this:
A [.myrole]#custom role# must be fulfilled by the theme.
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]
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.
> 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.
So, is it worse than HTML? Maybe, if you need those features often, but not for documentation where you'll rarely, if ever, use those.
Inline example:
pass:[<u>underlined</u>]
or
+++<u>underlined</u>+++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).
I'd guess Mozilla chosen a format most people are familiar with.
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.
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.
My biggest gripe was the lag to request ddg and then mdn and then parse it and pipe it. I wanted something simpler like `man` for mdn. Now i imagine having the documentation already in md and keeping it local, i'm a step closer and it'll be more powerful with tools like fzf, ripgrep, and mdcat.
Gotta check if there's already a search tool for MD that weighs heading levels, or code blocks, bold text, etc
Jokes aside, it's interesting to see at what lengths people go just to get it "in a format I prefer" rather than using the given format (and the other side not having any kind of structured format as it looks).
works great!
It would allow for easier reuse of the content.
That's a problem with a bad WYSIWYG editor, not HTML in general.
> authors were faced with the result of 15 years of people pasting rich content into the WYSIWYG editor, resulting in [a ton of garbled HTML markup]
... But you could have cleaned up the HTML.
> The beauty of Markdown, to you as a writer, is that it lets you concentrate on expressing concepts and hardly thinking about syntax at all.
I entirely disagree because there are few WYSIWYG editors for it and almost certainly not for "that one non-standard extension" everyone adds to their flavor.
I'll give them that HTML particularly sucks for code examples, which is a very good reason to switch, but the comparison in the article is not a very fair one - it's bungled HTML vs Markdown.
Not sure what the upsides and downsides are.
Indeed, if you’re going to make use of Markdown to store structured data like a config file, I wager the result will start looking a lot like YAML. At which point - why not just use YAML directly?
YAML is a decent solution to their problem which is:
they:
have:
- so
- many
- nested
- levels:
of:
configuration:
without:
any:
- abstractions &that-arent-ugly
Worked quite well as one-offs but I'm not sure that scales wrt its usability and maintenance.
Things like jupyter notebooks and observablehq.com seem to be bringing in a breath of fresh air to literate programming.
Markdown for comments in config files? Absolutely.
It works by embedding yaml code blocks into a markdown file.
It’s actually not completely awful and has proven somewhat useful to have a configuration clearly documented within the config.
https://github.com/Azure/autorest/blob/main/docs/generate/re...
That sounds unlikely. Where did you hear that?
It can't be. Using "markdown" for config really means building a shitty ad hoc configuration language and embedding it in markdown. I've seen this a few times and it's always a disaster.
The only way I've found to make configuration tolerable is to go in the opposite direction and turn it into code with a declarative eDSL. For example Pulumi's typescript API is an absolute godsend after years of toiling away on HCL and YAML.
Altogether, it is a great system though
Off topic: recommend a nodejs tool (or something client side?) to convert markdown to html to make article writing easier for custom sites?
Really? It was HTML for 17 years with over 11,000 pages. But I guess that’s not long-term sustainability?
I applaud the conversion, but don’t misrepresent the facts and what you inherited, Wil.
Before 2020, MDN was in a Wiki and editors could use a WYSIWYG interface, which was OK for relatively simple edits although for more involved stuff we often had to resort to the raw HTML source (and even for simple edits, the editor would often not generate the markup you might have expected). Being in a Wiki meant there was no pre-publication review process, and it was very hard to make systematic improvements to the content. You couldn't, for instance, create a single pull request updating dozens of files and review them all together. Whether that was sustainable, or whether overall quality just gradually declined - well, it was certainly really hard to maintain.
At the end of 2020 MDN content moved into GitHub, I think that's enabled us to make large-scale improvements to the content that wouldn't have been practical before, as well as to have a review process to ratchet up overall quality.
But this move also meant the WYSIWYG editor went away, and everyone was faced with editing the raw HTML source, all the time, and I really don't think that was a sustainable situation. We could I suppose have revived something like the WYSIWYG editor, but I think switching to a simpler source format was a better option.