diff --git a/docs/templates/ADOC.tmpl b/docs/templates/ADOC.tmpl
index 7ba5d3b1263..99d6921323b 100644
--- a/docs/templates/ADOC.tmpl
+++ b/docs/templates/ADOC.tmpl
@@ -1,4 +1,6 @@
 // set the attribute to true or leave empty, true without any quotes.
+// if the generated adoc file is used outside tabs, it renders correctly depending on the attribute set.
+// if inside, you need to also use the xxx_deprecation.adoc file. attributes can't be defined inside tabs.
 
 :show-deprecation: {{ .HasDeprecations }}
 
@@ -23,6 +25,8 @@ ifeval::[{show-deprecation} == true]
 {{- end }}
 |===
 
+{empty} +
+
 endif::[]
 
 [caption=]