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