diff --git a/cmd/shfmt/shfmt.1.scd b/cmd/shfmt/shfmt.1.scd
index e47790e9..def8d6e9 100644
--- a/cmd/shfmt/shfmt.1.scd
+++ b/cmd/shfmt/shfmt.1.scd
@@ -93,6 +93,9 @@ predictable. Some aspects of the format can be configured via printer flags.
 *-kp*, *--keep-padding*
 	Keep column alignment paddings.
 
+	This flag is *DEPRECATED* and will be removed in the next major version.
+	For more information, see: https://github.com/mvdan/sh/issues/658
+
 *-fn*, *--func-next-line*
 	Function opening braces are placed on a separate line.
 
diff --git a/syntax/printer.go b/syntax/printer.go
index 55cf69fc..b42f6f1b 100644
--- a/syntax/printer.go
+++ b/syntax/printer.go
@@ -55,6 +55,11 @@ func SpaceRedirects(enabled bool) PrinterOption {
 // Note that this feature is best-effort and will only keep the
 // alignment stable, so it may need some human help the first time it is
 // run.
+//
+// Deprecated: this formatting option is flawed and buggy, and often does
+// not result in what the user wants when the code gets complex enough.
+// The next major version, v4, will remove this feature entirely.
+// See: https://github.com/mvdan/sh/issues/658
 func KeepPadding(enabled bool) PrinterOption {
 	return func(p *Printer) {
 		if enabled && !p.keepPadding {