docs: write back custom dimensions (#63)

* docs: write back custom dimensions

* docs: bin limitation

* docs: update

Author: ZeRego

docs/references/assets/write-back-custom-dimension-1.png

@@ -4,6 +4,9 @@ import TablesConfigurationWriteBack from './assets/tables-configuration-write-ba
 import dbtCloudRunAutomatically from './assets/dbt-cloud-run-automatically.jpg';
 import writeBackMetrics from './assets/write-back-metrics.jpg';
 import refreshAfterWriteback from './assets/refresh-after-write-back.jpg';
+import writeBackCustomDimension1 from './assets/write-back-custom-dimension-1.png';
+import writeBackCustomDimension2 from './assets/write-back-custom-dimension-2.png';
+import writeBackCustomDimension3 from './assets/write-back-custom-dimension-3.png';
 
 # dbt Write-Back
 
@@ -55,6 +58,57 @@ Any custom metric that matches the definition of your new YAML metric will autom
 
 :::
 
+## Write-Back dimensions from custom dimensions
+
+You can build custom dimensions in Lightdash and write these back to your dbt project.
+
+We recommend using dbt write-back for custom dimensions that you're using/creating frequently so they become dimensions that are reusable, governed and available for everyone else to build from.
+
+:::info
+
+**What's the difference between a dimension and a custom dimension?**
+
+[Dimensions](/references/dimensions) written to your dbt project (or YAML dimensions) are reusable by everyone in your project and will show up in the list of available dimensions for a Table. [Custom dimensions](/references/custom-fields#custom-dimensions) are only saved in the chart they're used in and will not be saved in the list of `dimensions` available if you open the same Table to build a new chart.
+
+:::
+
+To get started, create a [custom dimension](/references/custom-fields#custom-dimensions) in the Explorer. Hover over the custom dimension in the sidebar and click on the three-dot menu, then `write back to dbt`.
+
+1. Click `write back to dbt`
+<img
+    src={writeBackCustomDimension1}
+    width="644"
+    height="805"
+    style={{display: 'block', margin: '0 auto 20px auto'}}
+/>
+2. Preview the dimension YAML and open a Pull Request.
+<img
+    src={writeBackCustomDimension2}
+    width="644"
+    height="805"
+    style={{display: 'block', margin: '0 auto 20px auto'}}
+/>
+3. Approve and merge the Pull Request in your dbt project.
+<img
+    src={writeBackCustomDimension3}
+    width="644"
+    height="805"
+    style={{display: 'block', margin: '0 auto 20px auto'}}
+/>
+
+Once the pull request with your new dimension is merged, you can click `refresh dbt` in Lightdash (or, if you're [using GitHub actions](../guides/cli/how-to-use-lightdash-deploy#automatically-deploy-your-changes-to-lightdash-using-a-github-action), your project will automatically refresh once your changes are merged).
+
+### Known limitations
+
+#### Bin dimensions
+
+Writing back bin dimensions is not supported at the moment. If you want to help test our beta feature, please reach out to support.
+
+#### Write-back dimensions automatically replacing custom dimensions
+
+At the moment, if you write back a custom dimension to your dbt project's YAML, the custom dimension will not be automatically replaced with the new, YAML dimension. Once your new dimension is created in dbt, you'll need to manually update your charts and replace the custom dimensions with the new dimension. 
+
+
 ## Write-Back models from the SQL Runner
 
 You can use Lightdash to build models in dbt from queries that you've built in the SQL runner. We recommend writing back models from the SQL runner if you're planning to use the query regularly so it can be easily used, governed and managed like other dbt models in your Lightdash project.