[hombre_fatal]

True, though gotchas exist when user intuition doesn't match with actual behavior regardless of whether they are mentioned in docs.

[chii]

Principle of least surprise.

If you need to write in the docs about a surprise that a user otherwise wouldn't have expected, may be it's a sign that the surprise should be fixed up such that it's not surprising behaviour.