Update doc

Author: dgarros

docs/docs/python-sdk/topics/object_file.mdx

@@ -2,13 +2,13 @@
 title: Manage data with Object Files
 ---
 
-# Manage data with Object filess
+# Manage data with Object files
 
 ## Introduction
 
-An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema.
+An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema. It provides a declarative way to define and manage resources in your Infrahub instance.
 
-Object files work well for models that don't change too often and/or that needs to be tracked in Git: Examples: Groups, tags, Users etc ..
+Object files work well for models that don't change too often and/or that need to be tracked in Git. Examples include: Groups, tags, Users, etc.
 Below is an example of an Object file that defines tags (`BuiltinTag`).
 
 ```yaml
@@ -23,22 +23,22 @@ spec:
     - name: Red
 ```
 
-Object files are meant to be used in an idempotent way and as such they would work better for models with a Human Friendly ID (hfid) defined.
+Object files are meant to be used in an idempotent way and as such they work better for models with a Human Friendly ID (HFID) defined. An HFID is a unique identifier that makes it easier to reference objects across different files and operations.
 
 ## Load Object files into Infrahub
 
-Object files can be loaded into Infrahub using the `infrahub load object` command.
+Object files can be loaded into Infrahub using the `infrahub object load` command.
 
 ```bash
 infrahub object load <path_to_object_file>
 ```
 
 Multiple object files can be loaded at once by specifying the path to multiple files or by specifying a directory.
 
-The object `object load` command will create/update the objects using an `Upsert` operation. All objects previously loaded will NOT be deleted in the Infrahub instance.
-Also, if some objects present in different files are identical are dependent on each other, the `object load` command will NOT calculate the dependencies between the objects and as such it's the reponsability of the users to execute the command in the right order.
+The `object load` command will create/update the objects using an `Upsert` operation. All objects previously loaded will NOT be deleted in the Infrahub instance.
+Also, if some objects present in different files are identical and dependent on each other, the `object load` command will NOT calculate the dependencies between the objects and as such it's the responsibility of the users to execute the command in the right order.
 
-### Validate the format of the object facilitates
+### Validate the format of object files
 
 The object file can be validated using the `infrahub object validate` command.
 
@@ -48,9 +48,9 @@ infrahub object validate <path_to_object_file>
 
 ## Object file format
 
-All object files must start with the following format, all other format will be automatically ignored
+All object files must start with the following format, all other formats will be automatically ignored.
 Each file is intended for one specific top level kind, but one file can include multiple nested objects of any kind.
-The kind of the top level object must be defined in spec/kind
+The kind of the top level object must be defined in spec/kind.
 
 ```yaml
 ---
@@ -62,12 +62,12 @@ spec:
     - [...]
 ```
 
-> Multiple documents in a single Yaml file are also supported, each document will be loaded as a separately. Documents are separated by `---`
+> Multiple documents in a single YAML file are also supported, each document will be loaded separately. Documents are separated by `---`
 
 ### Relationship of cardinality One
 
 A relationship of cardinality one can either reference an existing node via its HFID or create a new node if it doesn't exist.
-In the example below, both `site` and `primary_ip` are relationship of cardinality one.
+In the example below, both `site` and `primary_ip` are relationships of cardinality one.
 
 ```yaml
 ---
@@ -85,12 +85,12 @@ spec:
 
 ### Relationship of cardinality Many
 
-A relationship of cardinality many can reference existing nodes via their HFID or define nested objects
+A relationship of cardinality many can reference existing nodes via their HFID or define nested objects.
 
 #### Existing nodes referenced by their HFID
 
 Existing nodes can be referenced by their HFID in string format or in list format.
-In the example below, both `best_friends` and `tags` are relationship of cardinality many.
+In the example below, both `best_friends` and `tags` are relationships of cardinality many.
 
 > An HFID is composed of a single value, it's possible to use a string instead of a list
 
@@ -103,7 +103,7 @@ spec:
   data:
     - name: Mike Johnson
       height: 175
-      best_friends: # Relationship of cardinality many that referenced existing nodes based on their HFID
+      best_friends: # Relationship of cardinality many that references existing nodes based on their HFID
         - [Jane Smith, Max]
         - [Sarah Williams, Charlie]
       tags:
@@ -113,17 +113,17 @@ spec:
 
 #### Nested Objects
 
-When defining nested objects, the node will be automatically created if it doesn't exist and if their relationship between the parent object and the nested object it will be automatically inserted.
-For example, in the example below, the `owner` of a `TestingDog` doesn't need to be specify because it will be automatically inserted.
+When defining nested objects, the node will be automatically created if it doesn't exist and if the relationship between the parent object and the nested object exists, it will be automatically inserted.
+For example, in the example below, the `owner` of a `TestingDog` doesn't need to be specified because it will be automatically inserted.
 
-For 2 different syntaxes are supported:
+Two different syntax are supported:
 
-- A dictionnary with multiple value under data
+- A dictionary with multiple values under data
 - A list of objects
 
 ##### Nested objects as a dictionary
 
-In the example below, `tags` is a relationship of cardinality many that is defined as a dictionnary with multiple values under data.
+In the example below, `tags` is a relationship of cardinality many that is defined as a dictionary with multiple values under data.
 
 > The kind is optional here because there is only one option possible (not a generic)
 
@@ -149,7 +149,7 @@ For more complex cases, the list of objects format is more flexible.
 ##### Nested objects as a list of objects
 
 In the example below, `animals` is a relationship of cardinality many that is defined as a list of objects.
-Each object must contains a `data` key and each object can also define a specific `kind`.
+Each object must contain a `data` key and each object can also define a specific `kind`.
 
 > If the kind is not specified, it will be inferred from schema
 
@@ -177,4 +177,19 @@ spec:
 
 ### Support for Metadata
 
-Please stay tuned, the Object file does not support metadata yet, neither on attribute or relationship.
+Metadata support is planned for future releases. Currently, the Object file does not support metadata on attributes or relationships.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Objects not being created**: Ensure that the YAML syntax is correct and that the file follows the required format.
+2. **Dependency errors**: When objects depend on each other, load them in the correct order (dependencies first).
+3. **Validation errors**: Use the `infrahub object validate` command to check for syntax errors before loading.
+
+### Best Practices
+
+1. Use Human Friendly IDs (HFIDs) for all objects to ensure consistent referencing.
+2. Keep object files organized by model type or purpose.
+3. Validate object files before loading them into production environments.
+4. Use comments in your YAML files to document complex relationships or dependencies.