See #41827

service/prometheus.md

@@ -191,28 +191,32 @@ idle-dal-02.torproject.org with author "wario" and a comment:
       --matchers job=bacula --matchers alias=idle-dal-02.torproject.org \
       --ends-at "in 5 days" --created-by "wario"
 
-The comment and the author are optional, but it is strongly recommended to set
-them, so that others can understand the goal of the silence and can refer to you
-for questions.
+The author is optional and defaults to the local username. Make sure
+you have a valid user set in your configuration and to set a correct
+`--comment` so that others can understand the goal of the silence and
+can refer to you for questions. The user comes from the
+[`getpass.getuser`](https://docs.python.org/3/library/getpass.html#getpass.getuser) Python function, see that documentation on how
+to override defaults from the environment.
 
 The matchers option can be specified multiple times. All values of the matchers
 option must match for the silence to find alerts (so the values have an "and"
 type boolean relationship)
 
-starts-at is not specified in the example above and that implies that the
-silence starts from now. You can use starts-at for example for planning a
-silence that will only take effect at the start of a planned maintenance window
-in the future.
+The `--starts-at` option is not specified in the example above and
+that implies that the silence starts from "now". You can use
+`--starts-at` for example for planning a silence that will only take
+effect at the start of a planned maintenance window in the future.
 
-starts-at and ends-at both accept either ISO 8601 formatted dates or textual
-dates accepted by the [dateparser](https://pypi.org/project/dateparser/) python
-module.
+The `--starts-at` and `--ends-at` options both accept either ISO 8601
+formatted dates or textual dates accepted by the [dateparser](https://pypi.org/project/dateparser/)
+Python module.
 
 Finally, if you want to update a silence, the command is slightly different but
 the arguments are the same, except for one addition `silence-id` which specifies
 the ID of the alert that needs to be modified:
 
-    fab silence.update --comment="machine waiting for first backup - tpa/tpa/team#12345678" \
+    fab silence.update --silence-id=9732308d-3390-433e-84c9-7f2f0b2fe8fa \
+      --comment="machine waiting for first backup - tpa/tpa/team#12345678" \
       --matchers job=bacula --matchers alias=idle-dal-02.torproject.org \
       --ends-at "in 7 days" --created-by "wario"