As I skimmed through that section I noticed it wasn't immediately clear
whether a line of text was referring to the example above it or the one
below it.
It seems like this needs more information, like why you'd want to put
something in one stanza or the other, but I don't really know enough
about drone to give useful advice.
I was unhappy with the comments-in-yaml approach; it required
duplicating a lot of information and it was hard to find a balance
between "usefully thorough" and "readably concise.""