diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md
index 1abd817de..24bc6e654 100644
--- a/docs/reference/cli-commands.md
+++ b/docs/reference/cli-commands.md
@@ -720,8 +720,12 @@ current plan.
 
 When you update service configuration (by adding a layer), the services changed won't be automatically restarted. `pebble replan ` restarts them and brings the service state in sync with the new configuration.
 
-- The "replan" operation restarts `startup: enabled` services whose configuration have changed between when they started and now; if the configuration hasn't changed, replan does nothing.
-- Replan also starts `startup: enabled` services that have not yet been started.
+For `startup: enabled` services that are running:
+
+- If the service hasn't changed configuration since it started, replan does nothing to the service.
+- If the service has changed configuration since it started, replan restarts the service.
+
+Replan also starts any `startup: enabled` services that have not yet been started, or that have been manually stopped.
 
 ### Examples
 
diff --git a/docs/reference/layer-specification.md b/docs/reference/layer-specification.md
index 8ed014b6d..84d0fddb8 100644
--- a/docs/reference/layer-specification.md
+++ b/docs/reference/layer-specification.md
@@ -37,7 +37,7 @@ services:
             <description>
 
         # (Optional) Control whether the service is started automatically when
-        # Pebble starts. Default is "disabled".
+        # Pebble starts or performs a 'replan' operation. Default is "disabled".
         startup: enabled | disabled
 
         # (Optional) A list of other services in the plan that this service