I generally agree that the documentation is a problem. A lot of the code is commented, so if you can find a package in nixpkgs that is using the same language, you can usually do some copypaste, somehow find the function definition it's referencing, and then it's not so hard to make the changes to package your new package. But "somehow find the function definition it's referencing" is not always as easy as it sounds... I think it's the only way to learn though. The documentation just isn't up to the level it needs to be to be self-sufficient.

As for flakes, they're not that big a change. There's some entry point which you have to learn about - a special file (flake.nix) that defines inputs and outputs according to some predefined structure. But the output leafs are just normal nix code - it's just that there's some builtins that can't be used because they do side effects at runtime. But that's less important than it sounds, because if you're using nixpkgs (as a library/input or as a source for copypasting) then it's flake-safe.