Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

MDN converted to Markdown

openwebdocs.org

Post reply on HN
Print view View original

11–20 of 140 posts

Re: MDN converted to Markdown

#11

Post by wbamberg »

TedDoesntTalk wrote: post #9

> 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.

Re: MDN converted to Markdown

#12

Post by nerdponx »

swyx wrote: post #8
nerdponx wrote: post #6

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 lik…

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/636602dec7fec996…

> 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!

Re: MDN converted to Markdown

#13

Post by beebeepka »

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.

Not sure what the upsides and downsides are.

Re: MDN converted to Markdown

#14

Post by photoGrant »

TedDoesntTalk wrote: post #9

> 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.

Two L's in his name. You've carefully crafted a slight and it looks worse on you, especially considering your post is about correcting facts.

Re: MDN converted to Markdown

#15

Post by nneonneo »

beebeepka wrote: post #13

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. Not sure what the upsides and downsides are.

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?

Re: MDN converted to Markdown

#16

Post by liamwire »

wbamberg wrote: post #11
TedDoesntTalk wrote: post #9

> 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 p…

I think this is a fantastic reply, and written with the good grace that the GP didn’t show you. Thanks for the insight, Will.

Re: MDN converted to Markdown

#17

Post by xcambar »

beebeepka wrote: post #13

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. Not sure what the upsides and downsides are.

Sounds like literate programming. I've used it once or twice for training material and as "fancy" slides at an internal presentation.

Worked quite well as one-offs but I'm not sure that scales wrt its usability and maintenance.

Re: MDN converted to Markdown

#18

Post by throw_m239339 »

beebeepka wrote: post #13

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. Not sure what the upsides and downsides are.

Pretty sure that markdown wasn't imagined for that purpose, how would it even work?

Markdown for comments in config files? Absolutely.

Re: MDN converted to Markdown

#19

Post by smashed »

nerdponx wrote: post #12
swyx wrote: post #8

Earlier quoted context omitted.

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/636602dec7fec996…

> 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…

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.

Re: MDN converted to Markdown

#20

Post by kubanczyk »

nerdponx wrote: post #6

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 lik…

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?
Post reply on HN