Add troubleshooting section about NFD file encoding

Signed-off-by: Vincent Petry <vincent@nextcloud.com>

admin_manual/configuration_server/occ_command.rst

@@ -664,6 +664,8 @@ File operations
                              sharing user holds the ownership of the respective files.
                              There is however an option to enable moving incoming shares.
 
+.. _occ_files_scan_label:
+
 Scan
 ^^^^
 

admin_manual/issues/general_troubleshooting.rst

@@ -295,6 +295,33 @@ Users' Federated Cloud IDs not updated after a domain name change
 | ``occ dav:sync-system-addressbook``
 | ``occ federation:sync-addressbooks``
 
+.. _trouble-file-encoding-ext-storages:
+
+Troubleshooting file encoding on external storages
+--------------------------------------------------
+
+When using external storage, it can happen that some files with special characters will not
+appear in the file listing, or they will appear and not be accessible.
+
+When this happens, please run the :ref:`files scanner<occ_files_scan_label>`, for example with::
+
+  sudo -u www-data php occ files:scan --all
+
+If the scanner tells about an encoding issue on the affected file, please enable Mac encoding compatibility in the :ref:`mount options<external_storage_mount_options_label>`
+and then :ref:`rescan the external storage<occ_files_scan_label>`.
+
+.. note::
+   This mode comes with a performance impact because Nextcloud will always try both encodings when detecting files
+   on external storages.
+
+   Mac computers are using the NFD Unicode Normalization for file names which is different than NFC, the one used
+   by other operating systems. Mac users might upload files directly to the external storage using NFD normalized
+   file names. When uploading through Nextcloud, file names will always be normalized to the NFC standard for consistency.
+
+   It is recommended to let Nextcloud use external storages exclusively to avoid such issues.
+
+   See also `technical explanation about NFC vs NFD normalizations <https://www.win.tue.nl/~aeb/linux/uc/nfc_vs_nfd.html>`_.
+
 Troubleshooting contacts & calendar
 -----------------------------------