The documentation on Derby's security mechanisms is scattered across several manuals. This makes it hard for developers to figure out which security mechanisms are relevant for a given application. Here are 3 places where security documentation appears:
1) In the Developer's Guide section titled "Derby and security"
2) In the Admin Guide section titled "Derby Network Server advanced topics"
3) In the Reference Manual section titled "Derby properties" as well as the syntax sections on GRANT, REVOKE, CREATE/DROP ROLE, and CREATE FUNCTION/PROCEDURE.
It would be good to add a section which points the developer at all of this material. It might be sufficient to rewrite the top level "Derby and security" page of the Developer's Guide. The following white paper may help organize our thoughts about this: http://www.oracle.com/technetwork/java/javadb/securitywhitepaper10-159253.pdf