From 8464364a736528623e55db55439e35284d296409 Mon Sep 17 00:00:00 2001
From: James Cherti <60946298+jamescherti@users.noreply.github.com>
Date: Mon, 18 Aug 2025 10:56:43 -0400
Subject: [PATCH] Update README.md

---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index 40be20b..3b7c757 100644
--- a/README.md
+++ b/README.md
@@ -1287,6 +1287,20 @@ NOTE: `flyspell-mode` can become slow when using Aspell, especially with large b
 
 To configure **flyspell**, add the following to `~/.emacs.d/post-init.el`:
 ``` emacs-lisp
+;; The flyspell package is a built-in Emacs minor mode that provides
+;; on-the-fly spell checking. It highlights misspelled words as you type,
+;; offering interactive corrections. In text modes, it checks the entire buffer,
+;; while in programming modes, it typically checks only comments and strings. It
+;; integrates with external spell checkers like aspell, hunspell, or
+;; ispell to provide suggestions and corrections.
+;;
+;; NOTE: flyspell-mode can become slow when using Aspell, especially with large
+;; buffers or aggressive suggestion settings like --sug-mode=ultra. This
+;; slowdown occurs because Flyspell checks words dynamically as you type or
+;; navigate text, requiring frequent communication between Emacs and the
+;; external Aspell process. Each check involves sending words to Aspell and
+;; receiving results, which introduces overhead from process invocation and
+;; inter-process communication.
 (use-package ispell
   :ensure nil
   :commands (ispell ispell-minor-mode)