diff --git a/src/docs/arithmetic_side_effects.txt b/src/docs/arithmetic_side_effects.txt
index b8c0872522e..4ae8bce88ad 100644
--- a/src/docs/arithmetic_side_effects.txt
+++ b/src/docs/arithmetic_side_effects.txt
@@ -30,4 +30,4 @@ let _n = Decimal::MAX + Decimal::MAX;
 ```
 
 ### Allowed types
-Custom allowed types can be specified through the "arithmetic-side-effects-allowed" filter.
+Custom allowed types can be specified through the "arithmetic-side-effects-allowed" filter.
\ No newline at end of file
diff --git a/src/docs/similar_names.txt b/src/docs/similar_names.txt
index 13aca9c0bb7..f9eff21b679 100644
--- a/src/docs/similar_names.txt
+++ b/src/docs/similar_names.txt
@@ -1,6 +1,10 @@
 ### What it does
 Checks for names that are very similar and thus confusing.
 
+Note: this lint looks for similar names throughout each
+scope. To allow it, you need to allow it on the scope
+level, not on the name that is reported.
+
 ### Why is this bad?
 It's hard to distinguish between names that differ only
 by a single character.