I think it needs both.
Certainly the docs could do a better job of explaining the whole concept and implementation in the Arduino system.
But I also think that the current mechanism is non-intuitive. It's not so much syntactically confusing as it is semantically disconnected. It is a mode in which you want the pin to behave, and the way you enable that mode is with a command (digitalWrite) that has nothing to do with the mode of a pin, but is otherwise used to send data out on it. We've overloaded the semantics of digitalWrite with another command that changes the mode.
Does that make sense?
That's why I favor some solution that uses a pinMode command to accomplish this.
.andy