Add some notes on javadoc to CONTRIBUTING (#71924)

I've been writing a bunch of javadoc lately and have some opinions that
I feel might be useful to share in CONTRIBUTING.md. I'm no expert
though.

CONTRIBUTING.md

@@ -436,11 +436,16 @@ is to be helpful, not to turn writing code into a chore.
        regular comments in the code. Remember as well that Elasticsearch
        has extensive [user documentation](./docs), and it is not the role
        of Javadoc to replace that.
+        * If a method's performance is "unexpected" then it's good to call that
+           out in the Javadoc. This is especially helpful if the method is usually fast but sometimes
+           very slow (shakes fist at caching).
    12. Please still try to make class, method or variable names as
        descriptive and concise as possible, as opposed to relying solely on
        Javadoc to describe something.
-   13. Use `@link` and `@see` to add references, either to related
-       resources in the codebase or to relevant external resources.
+   13. Use `@link` to add references to related resources in the codebase. Or
+       outside the code base.
+       1. `@see` is much more limited than `@link`. You can use it but most of
+          the time `@link` flows better.
    14. If you need help writing Javadoc, just ask!
 
 Finally, use your judgement! Base your decisions on what will help other