Extend update docs to mention possible data fragmentation (#2164)

#### Reference Issues/PRs
<!--Example: Fixes #1234. See also #3456.-->

#### What does this implement or fix?

#### Any other comments?

#### Checklist

<details>
  <summary>
   Checklist for code changes...
  </summary>
 
- [ ] Have you updated the relevant docstrings, documentation and
copyright notice?
- [ ] Is this contribution tested against [all ArcticDB's
features](../docs/mkdocs/docs/technical/contributing.md)?
- [ ] Do all exceptions introduced raise appropriate [error
messages](https://docs.arcticdb.io/error_messages/)?
 - [ ] Are API changes highlighted in the PR description?
- [ ] Is the PR labelled as enhancement or bug so it appears in
autogenerated release notes?
</details>

<!--
Thanks for contributing a Pull Request to ArcticDB! Please ensure you
have taken a look at:
- ArcticDB's Code of Conduct:
https://github.com/man-group/ArcticDB/blob/master/CODE_OF_CONDUCT.md
- ArcticDB's Contribution Licensing:
https://github.com/man-group/ArcticDB/blob/master/docs/mkdocs/docs/technical/contributing.md#contribution-licensing
-->

Author: vasil-pashov

python/arcticdb/version_store/library.py

@@ -966,9 +966,9 @@ def append(
         metadata
             Optional metadata to persist along with the new symbol version. Note that the metadata is
             not combined in any way with the metadata stored in the previous version.
-        prune_previous_versions, default=False
+        prune_previous_versions
             Removes previous (non-snapshotted) versions from the database.
-        validate_index: bool, default=True
+        validate_index
             If True, verify that the index of `data` supports date range searches and update operations.
             This tests that the data is sorted in ascending order, using Pandas DataFrame.index.is_monotonic_increasing.
 
@@ -1099,6 +1099,9 @@ def update(
         If dynamic schema is used then data will override everything in storage for the entire index of ``data``. Update
         will not keep columns from storage which are not in ``data``.
 
+        The update will split the first and last segments in the storage that intersect with 'data'. Therefore, frequent
+        calls to update might lead to data fragmentation (see the example below).
+        
         Parameters
         ----------
         symbol
@@ -1151,6 +1154,25 @@ def update(
         2018-01-01     400
         2018-01-03      40
         2018-01-04       4
+
+        Update will split the first and the last segment intersecting with ``data``
+        >>> index = pd.date_range(pd.Timestamp("2024-01-01"), pd.Timestamp("2024-02-01"))
+        >>> df = pd.DataFrame({f"col_{i}": range(len(index)) for i in range(1)}, index=index)
+        >>> lib.write("test", df)
+        >>> lt=lib._dev_tools.library_tool()
+        >>> print(lt.read_index("test"))
+        start_index                     end_index  version_id stream_id          creation_ts         content_hash  index_type  key_type  start_col  end_col  start_row  end_row
+        2024-01-01  2024-02-01 00:00:00.000000001           0   b'test'  1738599073224386674  9652922778723941392          84         2          1        2          0       32
+        >>> update_index=pd.date_range(pd.Timestamp("2024-01-10"), freq="ns", periods=200000)
+        >>> update = pd.DataFrame({f"col_{i}": [1] for i in range(1)}, index=update_index)
+        >>> lib.update("test", update)
+        >>> print(lt.read_index("test"))
+        start_index                                    end_index  version_id stream_id          creation_ts          content_hash  index_type  key_type  start_col  end_col  start_row  end_row
+        2024-01-01 00:00:00.000000 2024-01-09 00:00:00.000000001           1   b'test'  1738599073268200906  13838161946080117383          84         2          1        2          0        9
+        2024-01-10 00:00:00.000000 2024-01-10 00:00:00.000100000           1   b'test'  1738599073256354553  15576483210589662891          84         2          1        2          9   100009
+        2024-01-10 00:00:00.000100 2024-01-10 00:00:00.000200000           1   b'test'  1738599073256588040  12429442054752910013          84         2          1        2     100009   200009
+        2024-01-11 00:00:00.000000 2024-02-01 00:00:00.000000001           1   b'test'  1738599073268493107   5975110026983744452          84         2          1        2     200009   200031
+
         """
         return self._nvs.update(
             symbol=symbol,
@@ -1168,13 +1190,15 @@ def update_batch(
         prune_previous_versions: bool = False,
     ) -> List[Union[VersionedItem, DataError]]:
         """
-        Perform an update operation on a list of symbols in parallel.
+        Perform an update operation on a list of symbols in parallel. All constrains on
+        [update](/api/library/#arcticdb.version_store.library.Library.update) apply to this call as well.
 
         Parameters
         ----------
         update_payloads: List[UpdatePayload]
             List `arcticdb.library.UpdatePayload`. Each element of the list describes an update operation for a
-            particular symbol. Providing the symbol name, data, etc.
+            particular symbol. Providing the symbol name, data, etc. The same symbol should not appear twice in this
+            list.
         prune_previous_versions: bool, default=False
             Removes previous (non-snapshotted) versions from the library.
         upsert: bool, default=False