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.
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]
> 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.
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.
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.
Like any good compression algorithm, asciidoctor optimizes for the common cases at the expense of the uncommon cases. For 98% of text you write, asciidoctor is probably much simpler than HTML
These are features that don't exist in Markdown though, unless there's some implementation that adds these. Also, the context of the parent comment and this post is documentation.
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.
At least an originally designed markdown falls back to HTML when it doesn’t directly support a particular feature. With Pandoc, markdown can fall back to LaTeX as well.
You can do the same in Asciidoc with the passthrough feature, either as an inline passthrough or a passthrough block. Granted, it's not syntax-less like Markdown, but it's there if you need it.
Inline example:
pass:[<u>underlined</u>]
or
+++<u>underlined</u>+++
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!
Well, that’s why Markdown was popular. It took existing conventions, codified them, and more importantly, crested a tool to convert them to HTML.
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.
The same is largely true of asciidoc. There are cases where you do kind of need to understand asciidoc, but mostly for features where in markdown you have to reach for the escape hatch of inline html.
I think it has a higher learning curve if you include everything in the language, because asciidoc has so many more features than markdown. But if you limit asciidoc to the subset that is comparable to markdown, I don't think it has a higher learning curve.
In fact, most of markdown is compatible with asciidoc. The markdown syntax for headings, monospace, quotes, lists, code blocks, and section breaks all work.
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.
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.
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.
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).
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.
> 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.
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.
DC needs a substantially higher voltage to kill you than AC. You can hold 100VDC wires in your fingers and be fine, though if you try this, I strongly recommend doing it with the other hand in your pocket and no path to ground, in case your hand is sweatier than average.
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.
AC is also used, in a sense, through every switching power supply. The phone you’re using that’s running on DC is actually taking the DC from battery, converting it to “AC” to buck it to the lower voltage, then rectifying it back to DC for the processors.
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.
AC has to deal with reactance and those associated losses in addition to resistance. AC resistance goes up with frequency because of the skin effect too.
"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.
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.
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.
I think an appealing thing about English is the ridiculous vocabulary. When it doesn’t have a word, it just steals one from another language. We have a French-based word that’s a “fancy” way to say an English-based synonym from the court vs common language situation with the Normans. Then borrowed liberally from Greek and Latin during the enlightenment, and every other language when colonialism kicked in (including a lot of botched Spanish). That constant borrowing is partly why our spelling is insane.
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.
There's also the budding euro-English, which is kinda funny because it is to some extent the revenge of all the words we've stolen from other European languages and then slowly turned into false-friends.
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!).
The stealing isn’t unique for sure. But most of the vocabulary in our language is borrowed words. Mostly just the “sight words” kids learn in early school is what remains of Old English. And many English words are the rougher equivalent of a borrowed, nicer words.
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.
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.
Before English, French was the international language of diplomacy, and it was very influental in science and humanities. Spoken French is as simple as Spanish at a glance. The writing system is peculiar, but still much more regular than the English one.
"I will have had run" and "I would have had been running" are not sensible. Perfect tenses indicate completion. If you try to "stack" two copies the auxiliary verb "have" to make some kind of double-perfect tense, it doesn't make any sense--it makes no more sense than saying "I wented to the store" or "I ated the food." There are reasons you can have utterances like "had had" in English, but it typically involves the other meaning of the word "have" (the non-auxiliary meaning), like "I had had steak, and James had had lasagna, but we both were still hungry."
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.
"By next month I will have had run 50 km" - is there a BETTER way to say this sentence?
It refers to the past from the prism of next month, but also RELATES it to that point in time
"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 had run 50 km" - is there a BETTER way to say this sentence?
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.
Spanish has a similar amount of tenses, some expressed in inflections, others through auxiliary verbs. Spanish doesn't have the obsession with the gerund ("I go home" is fine), but has (im)perfect past, plusquam perfect, and future tenses, combinations (no habría pensado: wouldn't have thought) and conditionals in all, just like English. They just don't correspond 1-1.
The subjunctive in English is a bit of joke in comparison to the Spanish one.
I'm not saying English has no nuance beyond my example.
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.
Spanish (at least some European variants) definitely has the "th-sounds" though. But similarly to English, it's not terribly important to get them right. The variants spoken in South America use sibilants instead.
Oh yeah, I studied Latin American Spanish so I did forget that Spaniards do have these sounds. But the vowel number is clearly smaller. The hardest sound is probably the "rr" rolling r
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
English has inconsistent spelling and pronunciation because it is a pigeon language, a mix of various Anglo-Saxon, Norse, Celtic, Dutch, and Norman French, then later with a lot of Latin and Greek words added.
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.
The word you're looking for is "pidgin" language, not "pigeon," but no, English is not a pidgin language. An example of a pidgin language is something like Tok Pisin. Pidgin languages essentially start out life as a not-quite-language, with such restricted vocabulary and grammar that there are concepts that can't be uttered, and such languages tend to grow back a grammar on top of that as they develop into a full, proper language.
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).
I'm curious, given the proximity of England to the Celtic world, why did English not borrow more from Gaelic? Hopefully it's not a stupid question, I realize that the language probably largely developed in Saxony, but I don't know much about how it made its way to the British isles.
There is a lot that is not clear about the Anglo-Saxon migration to Britain. The obvious archaeological evidence suggests a very abrupt shock that sees Roman Britain almost completely replaced by Anglo-Saxon migration in maybe a generation or two. This has traditionally been interpreted as effectively a complete population replacement, although this has been challenged in more recent archaeology.
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.
If I’m not mistaken the latest research on this topic incorporates the results of DNA studies that seem to suggest there was indeed a population replacement (made possible in part by the very large number of the Anglo-Saxon immigrants and the very much reduced, as a result of the upheavals after the departure of the Romans, number of Britons).
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)
The success of English is not the result of a “worse is better” situation. It’s the result of the fact that the English colonialists much of the world and then after colonialism ended and the world became more global through trade and communications, the biggest economy in the world with the biggest media industry in the history of the world spoke English.
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
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.
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.
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.
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?
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`.
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.
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
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)
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.
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.
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);`
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.
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.
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.
> 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).
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.
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.
I played with mdn-cli which was a neat cli that queries duckduckgo for the first mdn result and parses it to markdown. I then passed that through a parser to make it pretty, and then integrated it with my editor for getting fast documentation without too much context switching.
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
If there just would be some format and rendering engine that would us allow to display text nice. Let me think, something like HTML and a browser?
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).
I dream to be able to use the mdn/content repo directly on GitHub. Unfortunately the Markdown links are the "production" site ones and don't work in GitHub. It would be nice to have links that work there and their toolchain (called Yari if I understand well) should translate it when generating the MDN site.
Zeal is great but we should also mention https://kapeli.com/dash because zeal can use the docsets from dash for free, pretty nice i would say, and worth supporting dash if you have a mac.
> HTML cruft, like <span id="486uw3y3"> crept into the source, often from authors pasting HTML from another rich editing environment into the MDN WYSIWYG editor
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.
Recently I overheard that our company intends to use markdown for configuration purposes - replacing yaml and stuff. I am not against the idea but it did surprise me because while I am happy with writing documents in MD, it never occurred to me that it could be used for configs.
>it never occurred to me that it could be used for configs.
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.
My gut reaction is that it sounds like a terrible idea. Markdown is designed at the outset as a markup language, meant to imbue formatting and structure to human-readable text. But it lacks a formal grammar or a strictly defined mapping from syntax to parse tree, so different tools may interpret the same document differently (i.e. there are many Markdown “dialects”). Markdown has no inherent support for any kind of data types other than text; it has lists, but nothing that would obviously be “map” or key-value data structures.
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?
Whether using yaml or something more modern like Cue, nowadays a configuration language needs a semantic syntax checker (not just a parser), and tools to automate transformation. If you think you are OK building these with Markdown, go for it. But you'll find it's probably a bad idea in the end…
They are lacking implementations though and they are more about programming things than writing your config in them. Sure, you can put config in code, but that sounds like a terrible idea for non-DSLs.
Obsidian is my go-to note taking. I understand the flexibility of asciidoc, I don't see I'm going to adopt anything other than markdown, as a simply want one document formatting. Simple is better.
I’ve been using a writing app lately that uses markdown, and that has an export feature to produce documents that interpret your markup in various ways. It’s rather nice to use but is missing a few things: I wish there was a markdown tag to indicate “title” or “author byline” so that # and ## weren’t inconsistently reserved by certain formatting styles.
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?
While this is a good idea and we did something similar in my company, the only concern is the slippery slope of extending markdown. It is just a matter of time reaching this: https://xkcd.com/927/ .
> We might have gone on for another year or two with HTML-format documentation, and it would just have been a drag on our productivity. But we knew that this wasn't a sustainable foundation in the long term
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.
Sorry, I didn't intend to misrepresent, but yes, there is a fuller story here of course.
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.
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.