diff --git a/README.md b/README.md
index 8d5df588..673b6c01 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,9 @@ shadeDowngradedApi {
 The tasks have all the same flags as the extension, so you can change them separately, 
 their default value is to use the global one from the extension.
 
+If you are merging multiple downgraded jars, please merge from the downgradeJar tasks, and then shade on the resulting mono-jar.
+otherwise some API stubs may be missing, due to how shade only includes what is used.
+
 Optionally, you can also depend on the shadeDowngradedApi task when running build.
 
 ```gradle
diff --git a/docs/Bytecode Manipulation.md b/docs/Bytecode Manipulation.md
index d1ece635..3f052c82 100644
--- a/docs/Bytecode Manipulation.md	
+++ b/docs/Bytecode Manipulation.md	
@@ -38,6 +38,7 @@ Stubs have several other fields that change their behavior:
     mostly for things like reflection and runtime class definition.
 * `noSpecial` indicates that the stub should not be used for `INVOKESPECIAL` calls.
 * `downgradeVersion` adds an extra argument to the stub for the original version of the class, this is useful for multi-version stubs, such as reflection.
+* `excludeChild` prevent a stub from being applied to a child-class of the target. for example, `String#isEmpty` is since java 6, but `CharSequence#isEmpty` is since java 15.
 
 ### Modify