docarray
diff --git a/docarray/base_doc/doc.py b/docarray/base_doc/doc.py
@@ -61,39 +61,14 @@
 ExcludeType = Optional[Union['AbstractSetIntStr', 'MappingIntStrAny']]
 
 
-class BaseDoc(BaseModel, IOMixin, UpdateMixin, BaseNode):
+class BaseDocWithoutId(BaseModel, IOMixin, UpdateMixin, BaseNode):
     """
-    BaseDoc is the base class for all Documents. This class should be subclassed
-    to create new Document types with a specific schema.
-
-    The schema of a Document is defined by the fields of the class.
-
-    Example:
-    ```python
-    from docarray import BaseDoc
-    from docarray.typing import NdArray, ImageUrl
-    import numpy as np
-
-
-    class MyDoc(BaseDoc):
-        embedding: NdArray[512]
-        image: ImageUrl
-
-
-    doc = MyDoc(embedding=np.zeros(512), image='https://example.com/image.jpg')
-    ```
-
-
-    BaseDoc is a subclass of [pydantic.BaseModel](
-    https://docs.pydantic.dev/usage/models/) and can be used in a similar way.
+    BaseDocWoId is the class behind BaseDoc, it should not be used directly unless you know what you are doing.
+    It is basically a BaseDoc without the ID field.
+    !!! warning
+        This class cannot be used with DocumentIndex. Only BaseDoc is compatible
     """
 
-    id: Optional[ID] = Field(
-        description='The ID of the BaseDoc. This is useful for indexing in vector stores. If not set by user, it will automatically be assigned a random value',
-        default_factory=lambda: ID(os.urandom(16).hex()),
-        example=os.urandom(16).hex(),
-    )
-
     if is_pydantic_v2:
 
         class Config:
@@ -545,7 +520,7 @@ def parse_raw(
         :param allow_pickle: allow pickle protocol
         :return: a document
         """
-        return super(BaseDoc, cls).parse_raw(
+        return super(BaseDocWithoutId, cls).parse_raw(
             b,
             content_type=content_type,
             encoding=encoding,
@@ -582,3 +557,37 @@ def _exclude_docarray(
         )
 
     to_json = BaseModel.model_dump_json if is_pydantic_v2 else json
+
+
+class BaseDoc(BaseDocWithoutId):
+    """
+    BaseDoc is the base class for all Documents. This class should be subclassed
+    to create new Document types with a specific schema.
+
+    The schema of a Document is defined by the fields of the class.
+
+    Example:
+    ```python
+    from docarray import BaseDoc
+    from docarray.typing import NdArray, ImageUrl
+    import numpy as np
+
+
+    class MyDoc(BaseDoc):
+        embedding: NdArray[512]
+        image: ImageUrl
+
+
+    doc = MyDoc(embedding=np.zeros(512), image='https://example.com/image.jpg')
+    ```
+
+
+    BaseDoc is a subclass of [pydantic.BaseModel](
+    https://docs.pydantic.dev/usage/models/) and can be used in a similar way.
+    """
+
+    id: Optional[ID] = Field(
+        description='The ID of the BaseDoc. This is useful for indexing in vector stores. If not set by user, it will automatically be assigned a random value',
+        default_factory=lambda: ID(os.urandom(16).hex()),
+        example=os.urandom(16).hex(),
+    )
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -105,7 +105,8 @@ pytest-asyncio = ">=0.20.2"
 
 
 [tool.poetry.group.docs.dependencies]
-mkdocstrings = {extras = ["python"], version = ">=0.20.0"}
+mkdocstrings = {extras = ["python"], version = ">=0.23.0"}
+mkdocstrings-python= ">=1.7.0"
 mkdocs-material= ">=9.1.2"
 mkdocs-awesome-pages-plugin = ">=2.8.0"
 mktestdocs= ">=0.2.0"