add YAML page/section to the docs

[grahamgower]

It would be useful for readers to have a short explainer on YAML, exhibiting the major features relevant to writing Demes models. When I search for similar things on google, most of the top hits are rather terrible.

[jeromekelleher]

Good opportunity to steer people towards good practices too.

[grahamgower]

I've been writing fairly adhoc YAML so far - do you have suggestions for best practices that we should adopt? Indentation level? Something else?

[jeromekelleher]

The YAML you've produced all looks good to me - I guess we could find an auto formatter (Black for YAML?) and settle on that as our preferred way to do it? I don't think it's that simple though, as we want people to lay the models out in a readable way, and sometimes flow style is better than indentation, and vice versa.

Anyway, I don't have anything specific.

[grahamgower]

https://www.yaml.info/learn/bestpractices.html
The site also has some other useful info, including a nice tutorial and an extensive discussion on when quoting of strings is required (TLDR: its stupidly complicated and unreasonably onerous to figure it out from the YAML spec). The tute is still not something I'd just want to link to though, because we'd need to also say "ignore the stuff about aliases, anchors and tags"