diff --git a/docs/docs/api-reference/starlark-reference/directory.md b/docs/docs/api-reference/starlark-reference/directory.md
index 716b94e680..31ed2b7ff9 100644
--- a/docs/docs/api-reference/starlark-reference/directory.md
+++ b/docs/docs/api-reference/starlark-reference/directory.md
@@ -5,24 +5,32 @@ sidebar_label: Directory
 
 The `Directory` constructor creates a `Directory` object that represents a directory inside an existing service (see
 the [ServiceConfig][service-config] object).
-Directory object can be either a files artifact or a persistent directory, depending on the arguments passed to the 
+Directory object can be either one or many files artifacts or a persistent directory, depending on the arguments passed to the 
 constructor.
 
 ```python
+# composed with only one file artifact:
 file_artifact_directory = Directory(
-    artifact_name=files_artifact_1,
+    artifact_names=files_artifact_1,
 )
-# Or:
+# Or composed with multiple file artifacts:
+file_artifact_directory = Directory(
+    artifact_names=[files_artifact_1, files_artifact_2] 
+)
+# Or defining a persistent directory:
 persistent_directory = Directory(
     persistent_key="data-directory"
 )
 ```
 
-A directory composed of a files artifact will be automatically provisioned with the given files artifact content. In 
-the above example, `files_artifact_1` is a files artifact name. (see [upload_files][upload-files-reference], 
+A directory composed of one or many files artifacts will be automatically provisioned with the given files artifacts content. In 
+the above examples, `files_artifact_1` and `files_artifact_2` are files artifact names. (see [upload_files][upload-files-reference], 
 [render_templates][render-templates-reference] and [store_service_files][store-service-reference] to learn more about 
 on how to create file artifacts). 
 
+:::warning
+Take into account when using multiple file artifacts, like the example, if both files artifact contains a file or folder with the same name this will end up overwritten with no warranty on which one will take precedence.
+
 A persistent directory, as its name indicates, persists over service updates and restarts. It is uniquely identified 
 by its `persistent_key` and the service ID on which it is being used (a persistent directory cannot be shared across
 multiple services). When it is first created, it will be empty. The service can write anything in it. When the service