diff --git a/doc/intern.rst b/doc/intern.rst
index b71ad592f0..8e0df8fd38 100644
--- a/doc/intern.rst
+++ b/doc/intern.rst
@@ -67,8 +67,8 @@ Coding Guidelines
 * Max line length is 80 characters.
 * Provide spaces around binary operators if that enhances readability.
 * Use a space after a colon, but not before it.
-* Start types with a capital ``T``, unless they are pointers/references which
-  start with ``P``.
+* [deprecated] Start types with a capital ``T``, unless they are
+  pointers/references which start with ``P``.
 
 See also the `API naming design <apis.html>`_ document.
 
diff --git a/doc/manual.rst b/doc/manual.rst
index bcb1581dd0..e061927806 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -3870,7 +3870,14 @@ First class iterators
 There are 2 kinds of iterators in Nim: *inline* and *closure* iterators.
 An `inline iterator`:idx: is an iterator that's always inlined by the compiler
 leading to zero overhead for the abstraction, but may result in a heavy
-increase in code size. Inline iterators are second class citizens;
+increase in code size.
+
+Caution: the body of a for loop over an inline iterator is inlined into
+each ``yield`` statement appearing in the iterator code,
+so ideally the code should be refactored to contain a single yield when possible
+to avoid code bloat.
+
+Inline iterators are second class citizens;
 They can be passed as parameters only to other inlining code facilities like
 templates, macros and other inline iterators.