diff --git a/sbin/devd/devd.conf.5 b/sbin/devd/devd.conf.5
index 7782631e2384..80b23ec00401 100644
--- a/sbin/devd/devd.conf.5
+++ b/sbin/devd/devd.conf.5
@@ -40,7 +40,7 @@
 .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 .\" SOFTWARE.
 .\"
-.Dd August 18, 2020
+.Dd October 12, 2020
 .Dt DEVD.CONF 5
 .Os
 .Sh NAME
@@ -662,6 +662,59 @@ For example:
 // is a new comment, even though it is logically
 // part of the previous comment.
 .Ed
+.Ss Notes on Variable Expansion
+To prevent issues with special shell characters, the following happens for each
+variable
+.Ic $foo .
+.Bl -enum
+.It
+The characters
+.Dq $'
+are inserted.
+.It
+The string
+.Dq $foo
+is removed.
+.It
+The value of the
+.Ic foo
+variable is inserted into the buffer with all single quote characters
+prefixed by a backslash.
+.El
+.Pp
+See
+.Xr sh 1
+for what this construct means.
+It is safe in all context, except one: inside single quotes.
+If foo=meta and bar=var, then a rule like the following:
+.Bd -literal -offset indent -compact
+action "echo '$foo $bar'";
+.Ed
+will be presented to the shell via
+.Xr system 3
+as
+.Bd -literal -offset indent -compact
+echo '$'meta' $'var''
+.Ed
+which produces the following output:
+.Bd -literal -offset indent -compact
+$meta $var
+.Ed
+as its output.
+This is an unanticipated result.
+A future version of this software will change this behavior.
+Users are discouraged from using single quotes inside
+.Ic action
+value without due care.
+.Pp
+The above should be written as
+.Bd -literal -offset indent -compact
+action "echo $foo' '$bar"
+.Ed
+to produce a single argument to echo.
+Given the above expansion, juxtaposing bare variables with
+single quote expressions will produce the right output,
+regardless of the value of the variable.
 .Sh FILES
 .Bl -tag -width ".Pa /etc/devd.conf" -compact
 .It Pa /etc/devd.conf
@@ -733,6 +786,9 @@ detach 0 {
 The installed
 .Pa /etc/devd.conf
 has many additional examples.
+.Sh BUGS
+The variable expansion's interaction with single quotes is
+suboptimal and surprising.
 .Sh SEE ALSO
 .Xr cam 4 ,
 .Xr coretemp 4 ,