Re:Don’t Use Markdown for Documentation
by falcolas on Tuesday March 15, 2016 @05:25PM
(#11293138)
To your second point if you use a YAML parser, you can continue to consume and emit your JSON files and get comments for free. Plus, when you get to a use case JSON doesn't support, you can continue to use the same parser for the one-off.
[ Parent
| on HN ]
YAML claims to not be markup, but it clearly is a markup for data (significant whitespace/indentation, etc). When I want to do markup, I use Markdown.
When I want to data serialization, I use JSON. It's incredibly easy to strip comments (and whitespace, for that matter) from extended JSON before transmitting and/or parsing. I wrote `JSON.minify(..)` for that years ago, and it's literally never been a problem for me since.
YAML is markup in the same way that XML and JSON are markup. All three are methods of serializing data into text documents.
It also offers several advantages over JSON, in that it can also store and sanely represent relational data, has support for comments built into all YAML parsers, and it can be used to represent data structures that don't fall into the list/hash map paradigm.