Lets take this from the very first paragraph of the very first lesson that someone is supposed to learn
In a default installation of SilverStripe, your project directory is called mysite/ , and lives in the project root. Your theme directory, however, will be located one level deeper, under the themes/ folder. Because the code layer is detached from the UI, a given project can have multiple themes.
There is no /mysite/ directory any more. It’s now /app/. Ok, that’s fine. And I can already hear you saying “Well, why don’t I fix it?”. Because I didn’t break it. Someone at silverstripe chose to make this breaking change. That’s the person who should fix the documentation, so that, at the very least, they will learn that making breaking changes is a pain in the a** for the rest of us. And maybe, just maybe, they’ll be less inclined to make breaking changes next time. However, the fact that SS 4.1 introduced breaking changes, and 4.2 introduces breaking changes, and I’m darn certain that SS 5 will break all manner of shit, that I’m talking to deaf ears, and no-one will care.
Developers, module maintainers and everyone except the main SS dev team, want a stable platform. One where something I learn last year still works! Not something that they need to relearn every 6 months because some dev thought it’d be a neat idea to change the location of every file, or remove $themeDir because one in a hundred people want to use a multi-theme. Or requiring SSH access on the server to deploy SS (effectively preventing anyone on a shared platform from even trying SS).
/rant