I think documentation should go to $out/share/doc/<package>. nix has a fixupPhase that does the $out/doc -> $out/share/doc bit, but I think also making a subdir per package in doc/ is a good idea. Debian does this.