Added a bit about not modifying the .contents list directly.

1 files changed, 6 insertions, 0 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4663e25..caa46c9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -661,6 +661,12 @@ children using the ``.children`` generator::
      print(child)
  # The Dormouse's story
 
+If you want to modify a tag's children, use the methods described in
+`Modifying the tree`_. Don't modify the the ``.contents`` list
+directly: that can lead to problems that are subtle and difficult to
+spot.
+
+ 
 ``.descendants``
 ^^^^^^^^^^^^^^^^