Yaml syntax def docs

Yeah, I updated all examples, added notes for YAML and then some.

I might have missed a typo or two, but I don't think it's severe. We need the update.

Also, I updated from the ST2 docs because I think these are the most complete and merging the st3 branch into the st2 branch will be easier since it has less changes in comparison. I don't think we should generally differentiate between the two versions with branches because they are so alike that making changes would almost always require to merge into both branches.