In my discussion of Apache suexec I mentioned the apache2-suexec-custom Debian package, which allows you to change suexec's idea of its docroot and thus use suexec to run virtual host CGIs that aren't located under /var/www. If you're using suexec-custom, one of the obvious questions is what it's safe to set the suexec docroot to. If you read the manpage, you will hit this paragraph:

Do not set the [suexec] document root to a path that includes users' home directories (like /home or /var) or directories where users can mount removable media. Doing so would create local security issues. Suexec does not allow to set the document root to the root directory /.

This is all that the manpage has to say about this. In fact, this is all of the documentation you get about the security issues involved, period.

Perhaps the people who wrote this documentation felt that the security issues created here are obvious to everyone. If so, they were wrong. I at least have no idea what specifically makes including user home directories dangerous. It seems unlikely to be that users can create new executables, because if you're doing virtual hosting and using suexec, you're presumably already giving all of those different virtual hosting UIDs write access to their subdirectory in /var/www so they can set up their own CGIs. After all, suexec explicitly requires all of those CGIs and their containing directories to be owned by the target user, not you. And after that, what is there that applies to user home directories but not /var/www?

(It can't be that suexec will run arbitrary programs under user home directories, because suexec has to be run through Apache and you should not be telling Apache 'treat anything at all under this entire general directory hierarchy as a CGI through these URL'. If you tell Apache that your CGI-BIN directory is /usr/bin or /home or the like, you have already made a horrible mistake.)

This is a specific example of what is a general failing, namely not explaining why things are security issues. When you don't explain why things are a security problem, you leave people uncertain about what's safe and what isn't. Here, I've been left with no idea about what the important security properties of suexec's docroot actually are. The authors of the manpage have in mind some dangers, but I don't know what they are and as a result I don't know how to avoid them. It's quite possible that this will result in me accidentally configuring Apache and suexec in a subtly insecure way.

The explanation of why things are a security issue doesn't have to be deep and detailed; I don't demand, say, an example of how to exploit an issue. But it should be detailed enough that an outsider can see clearly what they need to avoid and broadly why. If you say 'avoid this general sort of setup', you need to explain what makes that setup dangerous so that people can avoid accidentally introducing a dangerous bit in another setup. Vagueness here doesn't help anyone.

(As a corollary, if you say that a general sort of setup is safe, you should probably explain why that's so. Otherwise you risk people making some small, harmless looking variant of the setup that is in fact not safe because it violates one of the assumptions.)

By the way, all of this applies to local system setup documentation too. If you know why something has to be done or not done in a particular way to preserve security, write it down in specific (even if it seems obvious to you now). Future readers of your documentation will thank you for being clear, and as usual this may well include your future self.

PS: It's possible that you don't know of any specific issues in your program but feel that it's probably not safe to use outside of certain narrow circumstances that you've considered in detail. If so, the documentation should just say this outright. Sysadmins and other people who care about the security properties of your program will appreciate the honesty.