Don’t Use Markdown for Documentation

Re:Don’t Use Markdown for Documentation by tirus on Tuesday March 15, 2016 @03:49PM (#11292459)

And then there's CommonMark: http://commonmark.org/

They aim to standardize the "markdown-like" formats into a single unified one. It's not done yet but it's certainly better than everyone for themselves.

[ Parent | on HN ]

Re:Don’t Use Markdown for Documentation by emodendroket on Tuesday March 15, 2016 @04:43PM (#11292824)

To be fair, the article literally links to that and mentions it as a possible solution.

[ Parent | on HN ]

Re:Don’t Use Markdown for Documentation by cryptos on Wednesday March 16, 2016 @09:24AM (#11297042)

Does anyone remember Creole wiki markup? It was born in a time when each wiki created its own syntax. Creole should become the standard for wikis, but it never got traction. I fear that it will be the same with commonmark.

[ Parent | on HN ]

Re:Don’t Use Markdown for Documentation by emodendroket on Wednesday March 16, 2016 @10:02AM (#11297337)

Probably would have worked better if they were allowed to call it "Standard Markdown" or had been able to get Gruber aboard.

[ Parent | on HN ]

Re:Don’t Use Markdown for Documentation by manyxcxi on Tuesday March 15, 2016 @04:35PM (#11292767)

This kind of reminds me of the XKCD[0] Standards comic strip. I love writing initial documentation in Markdown because I basically just punch out a text file with line breaks separating my sections/headers and add in some of the markup quickly after I get my content written.

It really is annoying though when I have to be careful about a convention that I'm using if I'm putting a README in BitBucket vs GitHub vs whatever else. Generally, if I'm just sticking to headers, lists, and quotes, I have no problem and everything works and I don't pay it another thought.

[0]: https://xkcd.com/927

[ Parent | on HN ]