ack. a quick search through the doc with  ":  " reveiled many places where we have a mess of whitespace in yml docs. but we should do that in one go and not mixed into this PR to avoid conflicts.