I'm a Debian user. I use it as part of my ISP operation. I've always been confused and frustrated about where to find files on Unix and Linux systems.
For instance, I do work on a FreeBSD system where I regularly have to deal with configuration files in /etc, /usr/local/etc, /var/smtpd/etc, /usr/local/www/conf, etc yada yada. Forget about docs. If there isn't a man page, it doesn't exist. Life's too short for me to keep track of where in hell's half acre these things are stored. Debian is a breath of fresh air. The File System Standard and the Package Manager together make a world of difference. The layout is clear and makes sense. I can actually find things. I can tell what's installed and what's not installed. I can see what needs what before I commit to a change. If you want my vote, go for the symlinks from /usr/doc to /usr/share/doc during the migration. For one thing, the /doc Alias in Apache won't be broken for any package (not the case right now) Once all the packages have been migrated to the new system, /usr/doc will have nothing but symlinks in it. When that happens, maybe replace /usr/doc with a symlink to /usr/share/doc. Cheers! Eric