From dc38b223c315c53da86505028c2f351da63be63a Mon Sep 17 00:00:00 2001
From: John Chen <john.x.chen@gmail.com>
Date: Sat, 18 Jul 2026 14:21:48 -0700
Subject: [PATCH] chore: W-23501725 update user guide

---
 doc/data-transfer-user-guide.md | 46 ++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/doc/data-transfer-user-guide.md b/doc/data-transfer-user-guide.md
index 967e25e..ef0cf4e 100644
--- a/doc/data-transfer-user-guide.md
+++ b/doc/data-transfer-user-guide.md
@@ -553,15 +553,13 @@ When a foreign key field references more than one object type (polymorphic), you
 
 **Best Practices**:
 
-- Include all fields necessary for business logic  
-- Include fields used in relationships (e.g., ParentProductId)  
-- Use dot-notation for parent field references (e.g., BasedOn.Code)  
-- Avoid including unnecessary fields to reduce data transfer size
+- Do NOT specify fields unless there is a special reason.
+- This tool will include all not-null fields that the authenticated user running the tool can access.
 
 **Example**:
 
 ```
-"fields": "Name, Code, ParentProductId, BasedOn.Code, Description"
+"fields": ""
 ```
 
 **9. Empty Filter Criteria**
@@ -1087,12 +1085,46 @@ sf data setup transfer \
 ## Frequently Asked Questions
 
 **Q:** The global key has an empty value. What should I do?  
-**A:** If a global key (for example, the `Code` field of `ProductComponentGroup`) is empty, update the value in the source org and rerun the CLI command. If the issue persists, investigate whether the problem exists in the source org or the target org. Open the `tmp/setup-transfer-payload.json` file in the directory from which you ran the CLI command. This file contains the exported data merged with the data set definition to identify the missing or incorrect values.  
+**A:** If a global key (for example, the `Code` field of `ProductComponentGroup`) is empty, update the value in the source org and rerun the CLI command. 
+
 **Q:** How to identify the issue is in source org or target org?  
-**A:** In the folder from which the CLI command is run, look for the tmp`/setup-transfer-payload.json` file. This file has the exported data combined with the data set definition.  
+**A:** In the folder from which the CLI command is run, look for the tmp`/setup-transfer-payload.json` file. This file has the exported data.  
+
 **Q:** Does the tool delete a record in the target org?  
 **A:** No
 
+**Q:** Objects in a managed package.
+**A:** The namespace prefix must be added to custom objects/fields in the dataset definition. Ex: "devopsimpkg15__" is the namespace prefix.
+```
+{
+  "dataSetName": "custom-object-managed-package",
+  "version": "1.0.0",
+  "exportSequence": {
+    "list": [
+      "devopsimpkg15__AdminTabLayout__c"
+    ]
+  },
+  "importSequence": {
+    "list": [
+      "devopsimpkg15__AdminTabLayout__c"
+    ]
+  },
+  "objects": {
+    "list": [
+      {
+        "objectName": "devopsimpkg15__AdminTabLayout__c",
+        "globalKeyField": "Name",
+        "fields": "Name",
+        "filterCriteria": "",
+        "foreignKeys": {
+          "list": []
+        }
+      }
+    ]
+  }
+}
+```
+
 ## **Additional Resources**
 
 - **GitHub Repository**: [plugin-data-setup-transfer](https://github.com/salesforcecli/plugin-data-setup-transfer/tree/main)