@Mistrel
I hope Helle's explanation made it clear.
sure, such things are to learn by the way you learn programming.
if you are programming for some time, maybe in different languages,
then such issues will be absolutely immanent for you.
once you understood how a computer works,
you can assume the performance by looking at the command and it's description a lot of times.
I admit, for me this all is somehow obvious, because I learned programming back in a time when it was a sacrilege to use a division by 2 instead a bitshift.
not each and every trick needs to be told in a documentation.
and mind you, now that you have discovered it yourself, you will never forget it and you will always have a look on performance issues.
so, it made you a better programmer that it was
not told in the doc.
__________________________________
This kind of thinking makes a Help file unnecessary. It assumes that Help files are for Experts. Since when do Experts need Help?
well, there is a broad range between "beginner" and "expert"...
"experts" also need a documentation, because only few can keep in mind every command and it's syntax of a bunch of languages.
I agree to you that a little chapter to explain "Performance Issues" would be a nice idea, but I doubt many would read it.
there a still people getting big eyes when they are told SpritePixelCollision is slow,
although it's explicitly told in the documentation of this command.