diff --git a/plugins/devkit/devkit-core/resources/documentation/plugin-descriptor.yaml b/plugins/devkit/devkit-core/resources/documentation/plugin-descriptor.yaml
index e3f82949f701..4d0e0118f9ad 100644
--- a/plugins/devkit/devkit-core/resources/documentation/plugin-descriptor.yaml
+++ b/plugins/devkit/devkit-core/resources/documentation/plugin-descriptor.yaml
@@ -41,7 +41,16 @@ elements:
             renderContexts: [doc_provider]
             deprecatedSince: "2026.1"
             deprecationNote: |
-              Proper module packaging should be used instead of this attribute: content modules should be packed into their own jars under `lib/modules/`.
+              Package attribute usage is discouraged and deprecated, content modules should be packaged into separate jars under `lib/modules/`.
+              IntelliJ Monorepository build system does it automatically when the attribute is not specified.
+              IntelliJ Platform Gradle Plugin allows doing that with `pluginModule` declaration since version 2.7.0.
+              
+              Note that after this attribute is removed, the classloader configuration will change.
+              While the class files of the module were packed into the main plugin's jar,
+              other modules could've accidentally accessed them. After they are separated into a module jar,
+              such accesses will start to throw `NoClassDefFoundError`.
+              Double-check that compile-time dependencies between modules match the module dependencies in module XMLs.
+              
               See [_Plugin Model_](https://youtrack.jetbrains.com/articles/IJPL-A-31){internal} for more details.
             requirement:
               required: no
diff --git a/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties b/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties
index b35a4cfd54c3..cf596f843d8f 100644
--- a/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties
+++ b/plugins/devkit/devkit-core/resources/messages/DevKitBundle.properties
@@ -234,9 +234,7 @@ inspections.plugin.xml.change.until.build.name=Change ''until-build'' to ''{0}''
 inspections.plugin.xml.change.until.build.family.name=Correct 'until-build' attribute
 inspections.plugin.xml.deprecated=Deprecated
 inspections.plugin.xml.deprecated.implementation.detail=Implementation plugins are no longer supported: use either a regular plugin or implement a product module
-inspections.plugin.xml.deprecated.package.attribute=Package attribute usage is discouraged and deprecated, content modules should be packaged into separate jars under `lib/modules/`. \
-  IntelliJ Monorepository build system does it automatically when the attribute is not specified. \
-  IntelliJ Platform Gradle Plugin allows doing that with `pluginModule` declaration since version 2.7.0.
+inspections.plugin.xml.deprecated.package.attribute=Package attribute usage is discouraged and deprecated, content modules should be packaged into separate jars under `lib/modules/`. Refer to attribute documentation for details.
 inspections.plugin.xml.add.version.tag=Add <version>
 inspections.plugin.xml.add.vendor.tag=Add <vendor>
 inspections.plugin.xml.module.descriptor.at.least.one.dependency=At least one <module> entry must be defined