Currently, the guide does not clarify why it is important for the library authors to target older Kotlin and Java releases, so they get confused.

I suggest there should be a section that explains the following:

• apiVersion: clarify why it is important, and suggest the strategy for the library authors
• languageVersion: clarify why it is important, and suggest the strategy for the library authors
• coreLibrariesVersion: clarify why it is important, and suggest the strategy for the library authors
• KotlinJvmCompile.jvmTarget: clarify why it is important, and clarify why bytecode version is not enough
• KotlinJvmCompile.Xjdk-release: clarify why it is important
• JavaCompile.release: clarify why it is important
• java.sourceCompatibility, java.targetCompatibility: clarify they should never be used with javac 11+ (they do not protect from NoSuchMethodError)

See also:

• https://kotlinlang.org/docs/api-guidelines-introduction.html
• https://speakerdeck.com/martinbonnin/metadataquoi
• https://www.morling.dev/blog/bytebuffer-and-the-dreaded-nosuchmethoderror