I have a different opinion myself though. While I don't use nix-env anymore I think it is important because serves as a bridge between nix and what people are typically expecting.
I think nix-env syntax should be improved to be similar what you expect with other package managers though.
Once you understand how nix operates you can then stop using nix-env.
I personally use nix for development. For every project I define the whole environment including all tools I need for development. This ensures that if someone needs to work on my project can get the same dev environment. If you add a tool like direnv to the mix it makes the experience much, much better, because then environment is automatically set up as soon as you enter the project directory.
The problem is: recommended by whom? The Nix Manual presents nix-env as the main way to install Nix packages. So, as long as the manual centers around nix-env, newcomers will try to use nix-env and get bitten by it.
The same is true for the NixOS Manual, it suggests that people install packages with nix-env before talking about declarative package management.
Also, I love home-manager, but it is perhaps too much for people who just want to dabble in Nix a bit. It would be nice if a simpler declarative way of managing packages was presented first. Perhaps surprisingly, another way is documented but it is deep in the nixpkgs manual:
https://nixos.org/manual/nixpkgs/stable/#sec-declarative-pac...