diff --git a/docs/client_generation.rst b/docs/client_generation.rst
new file mode 100644
index 00000000..f666852a
--- /dev/null
+++ b/docs/client_generation.rst
@@ -0,0 +1,70 @@
+.. _client_generation:
+
+Client generation
+===============================
+
+`drf-spectacular` aims to generate the most accurate schema possible under the constraints of OpenAPI 3.0.3.
+Unfortunately, sometimes this goal conflicts with generating a good and functional client.
+
+To serve the two main use cases, i.e. documenting the API and generating clients, we opt for getting the
+most accurate schema first, and then provide settings that allow to resolve potential issues with client generation.
+
+.. note:: TL;DR - Simply setting ``'COMPONENT_SPLIT_REQUEST': True`` will most likely yield the best
+ and most accurate client.
+
+.. note:: `drf-spectacular` generates warnings where it recognizes potential problems. Some warnings
+ are important to having a correct client. Fixing all warning is highly recommended.
+
+.. note:: For generating clients with CI, we highly recommend using
+ ``./manage.py spectacular --file schema.yaml --validate --fail-on-warn`` to catch potential problems
+ early on.
+
+Component issues
+----------------
+
+Most client issues revolve around the construction of components. Some client targets have trouble with
+``readOnly`` and `required`` fields like ``id``. Even though technically correct, the generated code may not
+allow creating objects with ``id`` missing for ``POST`` requests. Some fields like ``FileField`` behave very
+differently on requests and responses and are simply not translatable into a single component.
+
+The most useful setting is ``'COMPONENT_SPLIT_REQUEST': True``, where all affected components are split
+into request and response components. This takes care of almost all ``required``, ``writeOnly``, ``readOnly``
+issues, and generally delivers code that is easier to understand and harder to misuse.
+
+Sometimes you may only want to fix the ``required``/``readOnly`` issue without splitting all components.
+This can be explicitly addressed with ``'COMPONENT_NO_READ_ONLY_REQUIRED': True``. Because this setting waters
+down the correctness of the schema, we generally recommend using ``COMPONENT_SPLIT_REQUEST`` instead.
+
+``'COMPONENT_SPLIT_PATCH': True`` is already enabled by default as ``PATCH`` and ``POST`` requests clash
+on the ``required`` property and cannot be adequately modeled with a single component.
+
+Relevant settings:
+
+.. code:: python
+
+ # Split components into request and response parts where appropriate
+ 'COMPONENT_SPLIT_REQUEST': False,
+ # Aid client generator targets that have trouble with read-only properties.
+ 'COMPONENT_NO_READ_ONLY_REQUIRED': False,
+ # Create separate components for PATCH endpoints (without required list)
+ 'COMPONENT_SPLIT_PATCH': True,
+
+
+
+Enum issues
+-----------
+
+Some generator targets choke on combined enum components or having a ``null`` choice on a ``nullable: true``
+field. Even though it is the correct way (according to the specification), it sadly breaks some generator targets.
+Setting ``'ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE': False`` will create a less accurate schema that tends to offend
+fewer generator targets.
+
+For more information please refer to the `official documentation `_ and
+more specifically the `specification proposal `_.
+
+Relevant settings:
+
+.. code:: python
+
+ # Adds "blank" and "null" enum choices where appropriate. disable on client generation issues
+ 'ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE': True,
diff --git a/docs/index.rst b/docs/index.rst
index 613f8167..2e1bae6f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,6 +27,7 @@ Table of Contents
readme.rst
settings.rst
customization.rst
+ client_generation.rst
faq.rst
blueprints.rst
drf_yasg.rst
diff --git a/docs/settings.rst b/docs/settings.rst
index cbe8c8d0..0ef4016a 100644
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -1,3 +1,5 @@
+.. _settings:
+
Settings
========