Always document security-related configurations, permissions, and behaviors explicitly and comprehensively. When documenting security features: 1. Clearly specify required permissions and roles 2. Note version-specific security behavior changes 3. Explicitly state configuration inheritance rules and exceptions 4. Highlight security-critical settings with warnings or notes For example, when documenting an API that interacts with protected resources: ``` IMPORTANT: This action requires specific permissions. In {es} 8.1 and later, the superuser role doesn't have write access to system indices. If you execute this request as a user with the superuser role, you must have an additional role with the `allow_restricted_indices` privilege set to `true` to delete system indices. ``` For configuration documentation: ``` NOTE: Transport profiles do not inherit TLS/SSL settings from the default transport. The `xpack.security.transport.ssl.enabled` setting is an exception that controls SSL for both default transport and any transport profiles. ``` Clear and complete security documentation prevents misconfigurations that could lead to vulnerabilities or access issues.