[5.2.x] Fixed #36587 -- Clarified usage of `list.insert()` for upload handlers.

Thanks Baptiste Mispelon for the report

Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>

Backport of afe6634146d0fe70498976c49d2eb4d745aa9064 from main.

1 files changed, 4 insertions, 3 deletions

diff --git a/docs/topics/http/file-uploads.txt b/docs/topics/http/file-uploads.txt
index b9a9bbf416..fa1694af1d 100644
--- a/docs/topics/http/file-uploads.txt
+++ b/docs/topics/http/file-uploads.txt
@@ -288,9 +288,10 @@ handler to your upload handlers like this::
 
     request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
 
-You'd probably want to use ``list.insert()`` in this case (instead of
-``append()``) because a progress bar handler would need to run *before* any
-other handlers. Remember, the upload handlers are processed in order.
+Using ``list.insert()``, as shown above, ensures that the progress bar handler
+is placed at the beginning of the list. Since upload handlers are executed in
+order, this placement guarantees that the progress bar handler runs before the
+default handlers, allowing it to track progress across the entire upload.
 
 If you want to replace the upload handlers completely, you can assign a new
 list::