add documentation about how to comment directives

Directive.md

@@ -67,3 +67,23 @@ f() {
 ```
 
 Silencing parser errors is purely cosmetic; any parser error found will still stop ShellCheck at the point of the error.
+
+## Documenting directive use
+
+To document why a specific directive was used, it is recommended to add a comment.
+
+The comment can be added on the preceding line. This is the recommended option for long comments.
+
+```sh
+# this is intentional because of reasons
+# that are long and need explaining
+# shellcheck disable=SC1234
+statement_where_warning_should_be_disabled
+```
+
+The comment can also be added at the end of the directive line. This is the recommended option for short comments.
+
+```sh
+# shellcheck disable=SC1234 # this is intentional
+statement_where_warning_should_be_disabled
+```