Smiley,
Good points and I partly/mostly agree. Your post brings up a long held concern of mine that I'll contribute here rather than start a new thread.
That is:
I think it is important that new/intermediate users are aware of and understand, at least in the broad outlines, what is being simplified for them and what they are being shielded from. It doesn't have to be understood at first, or even in any great detail but the context should be there/presented so that the scope of learning and experience is not limited to 'Arduino' but can be scaled to a larger context.
This can be handled through documentation and overview type content. The Arduino project is very enabling and easy to work with. This is its brilliance. My concern is that having been buffered from the underlying complexity, users become locked into or see only the Arduino way of things. Said another way, I think the Arduino project should provide for users growing beyond Arduino, should they choose or need to.
It could be argued (if one agrees with this POV) that this task is best served by 3rd party books/sites. I would agree to an extent but I think there is a place/need on the Arduino site/within the docs to describe and detail what is being done (simplified), what the trade-offs are, and where limitations might be encountered. Also what some 'next steps' might be. This is not the sort of thing one does (or even can do) while a project is being developed but I think it is completely in scope and appropriate to an Arduino 1.0 milestone.
Oh, and I'd like line numbers displayed in the IDE 