📝 docs(appauthor): clarify None vs False on Windows

docs/explanation.rst

@@ -224,7 +224,10 @@ documentation <https://docs.microsoft.com/en-us/windows/win32/shell/known-folder
 
 Key behaviors:
 
-- ``appauthor`` adds a parent directory: ``AppData\Local\<Author>\<App>``
+- ``appauthor`` adds a parent directory: ``AppData\Local\<Author>\<App>``. When ``appauthor`` is ``None`` (the default),
+  it falls back to ``appname``, producing a doubled path like ``AppData\Local\MyApp\MyApp``. This follows the Windows
+  convention of grouping applications by publisher. If your application does not need an author directory, pass
+  ``appauthor=False`` to get ``AppData\Local\MyApp`` instead.
 - ``roaming=True`` switches from ``AppData\Local`` to ``AppData\Roaming``, which syncs across machines in a Windows
   domain. Use roaming for user preferences that should follow the user; use local (default) for machine-specific data
   like caches.

docs/howto.rst

@@ -222,6 +222,30 @@ See :ref:`xdg-env-vars` for the full list of supported XDG variables, and the :r
  Platform-specific recipes
 ***************************
 
+Windows: controlling the author directory
+=========================================
+
+On Windows, ``platformdirs`` creates a two-level directory structure: ``AppData\Local\<appauthor>\<appname>``. When
+``appauthor`` is omitted (``None``), it defaults to ``appname``, producing a doubled path like
+``AppData\Local\MyApp\MyApp``. Choose the right value based on your needs:
+
+.. code-block:: python
+
+    from platformdirs import user_data_dir
+
+    # Explicit author -- AppData\Local\AcmeCompany\MyApp
+    user_data_dir("MyApp", "AcmeCompany")
+
+    # No author -- AppData\Local\MyApp (flat structure)
+    user_data_dir("MyApp", appauthor=False)
+
+    # Default (appauthor=None) -- AppData\Local\MyApp\MyApp
+    # appauthor falls back to appname
+    user_data_dir("MyApp")
+
+Use an explicit author string when you publish multiple apps under the same organization. Use ``appauthor=False`` when
+you want a flat structure with just the app name. On non-Windows platforms, ``appauthor`` is always ignored.
+
 Windows: roaming vs local profiles
 ==================================
 

docs/parameters.rst

@@ -75,14 +75,22 @@ directory is returned without any app-specific subdirectory.
 ``appauthor``
 =============
 
-The app author or distributing organization. On Windows, this adds an additional parent directory:
+The app author or distributing organization. On Windows, this adds an additional parent directory above ``appname``:
 
 .. code-block:: pycon
 
     >>> user_data_dir("SuperApp", "Acme")  # on Windows
     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp'
 
-Set to ``False`` to suppress the author directory even on Windows:
+When ``None`` (the default), ``appauthor`` falls back to ``appname``, which means the app name appears **twice** in the
+path:
+
+.. code-block:: pycon
+
+    >>> user_data_dir("SuperApp")  # on Windows, appauthor defaults to appname
+    'C:\\Users\\trentm\\AppData\\Local\\SuperApp\\SuperApp'
+
+Set to ``False`` to suppress the author directory entirely:
 
 .. code-block:: pycon
 

docs/tutorial.rst

@@ -60,6 +60,15 @@ The result depends on the platform you're running on:
 
           'C:\\Users\\<you>\\AppData\\Local\\AcmeCompany\\MyApp'
 
+Notice on Windows the path includes both the author (``AcmeCompany``) and the app name (``MyApp``). If we omit
+``appauthor``, it defaults to ``appname``, producing ``AppData\Local\MyApp\MyApp``. To get a flat
+``AppData\Local\MyApp``, pass ``appauthor=False``:
+
+.. code-block:: pycon
+
+    >>> user_data_dir("MyApp", appauthor=False)  # on Windows
+    'C:\\Users\\<you>\\AppData\\Local\\MyApp'
+
 Each function returns a :class:`str`. If we prefer a :class:`~pathlib.Path`, we use the ``_path`` variant:
 
 .. code-block:: pycon

src/platformdirs/api.py

@@ -50,6 +50,13 @@ def __init__(  # noqa: PLR0913, PLR0917
 
         Typically, it is the owning company name. Defaults to `appname`. You may pass ``False`` to disable it.
 
+        .. note::
+
+            On Windows, the directory structure is ``<base>/<appauthor>/<appname>``. When ``appauthor`` is ``None`` (the
+            default), it falls back to ``appname``, resulting in ``<base>/<appname>/<appname>`` (e.g.
+            ``AppData/Local/myapp/myapp``). Pass ``appauthor=False`` to omit the author directory entirely and get
+            ``<base>/<appname>``.
+
         """
         self.version = version
         """An optional version path element to append to the path.